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System Requirements 

Each utility requires different amounts of memory. 

Macro Assembler - 96K bytes of memory minimum: 
64K bytes for code and static data 
32K bytes for run space 
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lOK bytes for run space 
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same physical disk from which the input was taken. 
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disks during operation on a one-drive 

configuration. Therefore, two disk drives is a 
more practical configuration. 



Microsoft 

Welcome to the Microsoft (R) family of products. 

Microsoft Corporation continues to supply consistently 
high-quality software for all types of users. 

In addition to the Macro Assembler and Microsoft BASIC 
interpreter, Microsoft sells other full-feature language 
compilers, language subsets, and operating system products. 
Microsoft offers a "family" of software products that both 
look alike from one product to the next, and can be used 
together for effective program development. 

For more information about other Microsoft -. products, 
contact: 

Microsoft Corporation 

10700 Northup Way 
Bellevue, WA 98004 

(206) 828-8080 
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GENERAL INTRODUCTION 



The Microsoft Macro Assembler Manual includes utility 
programs used for developing assembly language programs. In 
addition, the Microsoft LINK Linker Utility and DEBUG are 
used with of Microsoft's 16-bit language compilers. 



Major Features 



Macro Assembler Utility 

Microsoft's Macro Assembler is a powerful assembler for 
8086 based computers. 

Macro Assembler supports most of the directives found in 
Microsoft's Macro Assembler for the 8080. Macros and 
conditionals are Intel 8080 standard. 

Macro Assembler is upward compatible with Intel's 
ASM-86, except Intel codemacros, macros, and a few $ 
directives. 

Macro Assembler offers relaxed typing so that if you 
enter a typeless operand for an instruction that accepts 
only one type of operand. Macro Assembler assembles the 
statement correctly instead of returning an error 
message. 
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Microsoft LINK Linker Utility (Technical Information Only) 

MS-LINK is a virtual linker, which can link programs 
that are larger than available memory. 

MS-LINK produces relocatable executable object code. 

MS-'LINK processes overlays that you define. 

MS-LINK can perform multiple library searches, using a 
dictionary library search method. 

MS-LINK prompts you for input and output modules and 
other link session parameters. 

MS-LINK can be run with an automatic response file to 
answer the Linker prompts. 



Microsoft LIB Library Manager 

MS-LIB can add, delete, and extract modules in your 
library of program files. 

MS-LIB prompts you for input and output file and module 
names. 

MS-LIB can be run with an automatic response file to 
answer the library prompts. 

MS-LIB produces a cross-reference of symbols in the 
library modules. 



Microsoft CREF Cross-Reference Utility 

MS-CREF produces a cross-reference listing of all 
symbolic names in the Macro Assembler source program, 
giving both the source line number of the definition and 
the source line numbers of all other references to the 
symbols. 



Microsoft DEBUG Utility 

DEBUG provides a controlled testing environment for 
binary and executable object files. 

DEBUG eliminates the need to reassemble a program to see 
if a problem has been fixed by a minor change. 
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DEBUG allows you to alter the contents of a file or the 

contents of a CPU register, and then immediately 

reexecute a program to check on the validity of the 
changes. 

Using These Manuals 



These manuals are designed to be used as a set and 
individually. Each manual is mostly self-contained and 
refers to the other manuals only at junctures in the 
software. The overview given below describes the flow of 
program development from creating a source file through 
program execution. The processes described in this overview 
are echoed and expanded in overviews in each of the manuals 
contained in the Microsoft Macro Assembler Manual . 

Also, note that each manual has its own index. 

Figure 1 illustrates an overview of the Microsof t Macro 
Assembler Manual . 
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Figure 1. Overview, Macro Assembler Manual 



Each of these manuals is used independently. References 
between manuals reflect junctures in the software. 
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Syntax Notation 



The following notation is used throughout this manual in 
descriptions of command and statement syntax: 

[ 1 Square brackets indicate that the enclosed entry is 
optional. 

< > Angle brackets indicate data you must enter. When 
the angle brackets enclose lower case text, you 
must type in an entry defined by the text; for 
example, <filename>. When the angle brackets 
enclose upper case text, you must press the key 
named by the text; for example, <RETURN> . 

( } Braces indicate that you have a choice between two 
or more entries. At least one of the entries 
enclosed in braces must be chosen unless the 
entries are also enclosed in square brackets. 

... Ellipses indicate that an entry may be repeated, as 
many times as needed or desired - 

CAPS Capital letters indicate portions of statements or 
commands that must be entered, exactly as shown. 



All other punctuation, such as commas, coloi\s, slash marks, 
and equal signs, must be entered exactly as shown. 

Figure 2 illustrates the syntax notation used in this 
manual. 
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You have an option; 
you may stop herer 
or enter more. 

Enter a value 
here to replace the 
"dummy" entry and 
the angle brackets 






Enter as many more 
parameters as you 
want, up to end of line 



i 



CALL (<parameter> [r<parameter>. . . ] ) <RETURN> 

I I I ■ 

Enter punctuation as shown 



Enter CAPS Upper case 

exactly as inside angle 

shown Figure 2. syntax Notation ^"^'^^^S' P'^^SS 

this key 
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Learning More about Assembly Language Programming 



These manuals explain how to use MS-DOS utilities and 
features, but they do not teach you how to program in 
assembly language. 

We assume that you have had some experience programming in 
assembly language. If you do not have any experience, we 
suggest two courses: 

1. Gain some experience on a less sophisticated 
assembler . 

2. Refer to any or all of the following books for 
assistance: 



Morse, Stephen P. The 8086 Primer. Rochelle Park, 
NJ: Hayden Publishing Co., 1980. 

Rector, Russell and George Alexy. The 8086 Book . 
Berkeley, CA: Osbourne/McGraw-Hill , 1980. 

The 8086 Family User's Manual . Santa Clara, CA: 
Intel Corporation, 1979. 

8086/8087/8088 Macro Assembly Language Reference 
Manual. Santa Clara, CA: Intel Corporation, 
1980. 



NOTE 

Some of the information in 
these books was based on 
preliminary data and may not 
reflect the final functional 
state of the microprocessors. 
Information in your Microsoft 
manuals was based on 
Microsoft's development of its 
16-bit software for the 8086 
and 8088. 
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Overview of Program Development 



This overview describes generally the steps of program 

development. Each step is described fully in the individual 

product manuals. The numbers in the descriptions match the 
numbers in the facing diagram. 

1. Use EDLIN (the editor in Microsoft's MS-DOS), or 
other MS-DOS editor, to create an 8086 assembly 
language source file. Give the source file the 
filename extension .ASM (Macro Assembler recognizes 
.ASM as the default) . 

2. Assemble the source file with Macro Assembler, 
which outputs ap assembled object file with the 
default filename extension .OBJ (2a) . Assembled 
files, your program files (2b), can be linked 
together in step 3. 

Macro Assembler (optionally) creates two types of 
listing file: 

(2c) a normal listing file which shows assembled 
code with relative addresses, source 
statements, and full symbol table; 

(2d)a cross-reference file, a special file with 
special control characters that allow MS-CREF 
(2e) to create a list showing the source line 
number of every symbol's definition and all 
references to it (2f ) . When a cross-reference 
file is created, the normal listing file (with 
the .LST extension) has line numbers placed 
into it as references for line numbers 
following symbols in the cross-reference 
listing. 



3. Link one or more .OBJ modules together, using 
MS-LINK, to produce an executable object file with 
the default filename extension .EXE (3a) . 

While developing your program, you may want to 
create a library file for MS-LINK to search to 
resolve external references. Use MS-LIB (3b) to 
create user library file(s) (3c) from existing 
library files (3c) and/or user program object files 
(2b). 
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4. Run your assembled and linked program, the .EXE 
file (3a), under MS-DOS (4). If your program does 
not run properly, use the DEBUG utility to locate 
any errors. 
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System Requiroaents 

The Macro Assembler Utility requires 96K bytes of memory 
minimum: 

64K bytes for code and static data 
32K bytes for run space 

Disk drive (s) 

One disk drive if and only if output is sent to the 
same physical disk from which the input was taken. 
The Macro Assembler Utility does not allow time to 
swap disks during operation on a one-drive 
configuration. Therefore, two disk drives is a 
more practical configuration. 
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Features of Macro Assembler 

Microsoft's Macro Assembler is a very powerful assembler for 
8086-based computers. Macro Assembler incorporates many 
features usually found only in large computer assemblers. 
Macro assembly, conditional assembly, and a variety of 
assembler directives provide all the tools necessary to 
derive full use and full power from an 8086, 8087, or 8088 
microprocessor. Although Macro Assembler is more complex 
than any other microcomputer assembler, it is easy to use. 

Macro Assembler produces relocatable object code. Each 
instruction and directive statement is given a relative 
offset from its segment base. The assembled code can then 
be linked using Microsoft's MS-LINK utility to produce 
relocatable, executable object code. Relocatable code can 
be loaded anywhere in memory. Thus, the program can execute 
where it is most efficient, instead of in some fixed range 
of memory addresses. 



In addition, relocatable code means that programs can be 
created in modules, each of which can be assembled, tested, 
and perfected individually. This saves receding time 
because testing and assembly are performed on smaller pieces 
of program code. Also, all modules can be error-free before 
being linked together into larger modules or into the whole 
program. 
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Figure 1. The Assembly Process 
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Macro Assembler supports Microsoft's complete 8080 macro 
facility, which is Intel 8080 standard. The macro facility 
permits the writing of blocks of code for a set of 
instructions used frequently. The need for receding these 
instructions each time they are required in the program is 
eliminated . 

These blocks of code are called macros. The instructions 
are the macro definition. Each time the set of instructions 
is needed, instead of receding the set of instructions, a 
simple "call" to a macro is placed in the source file. 
Macro Assembler expands the macro call by assembling the 
block of instructions into the program automatically. The 
macro call also passes parameters to the assembler for use 
during macro expansion. The use of macros reduces the size 
of a source module because the macro definitions are given 
only once; other occurrences are one-line calls. 

Macros can be "nested," that is, a macro can be called from 
inside another macro block. Nesting of macros is limited 
only by memory. 

The macro facility includes repeat, indefinite repeat, and 
indefinite repeat character directives for programming 
repeat block operations. The MACRO directive can also be 
used to alter the action of any instruction or directive by 
using its name as the macro name. When any instruction ot 
directive statement is placed in the program. Macro 
Assembler first checks the symbol table it created to see if 
the instruction or directive is a macro name. If it is, 
Macro Assembler "expands" the macro call statement by 
replacing it with the body of instructions in the macro's 
definition. If the name is not defined as a macro, Macro 
Assembler tries to match the name with an instruction or 
directive. The MACRO directive also supports local symbols 
and conditional exiting from the block if further expansion 
is unnecessary. 



INTRODUCTION 



Page 4 



statement 
statement 
statement 
macro call 
statement 


■^ 




\ 


r 




name MACRO x 




E 


NDM 





When the assembler 
encounters a macro 
call, it finds the 
MACRO block and 
replaces the call 
with the block of 
statements that 
define the macro. 



name MACRO x 



name 1,2 



ENDM 



Nested MACRO call: 
name defined else- 
.where as a macro, 
is "expanded" 
during assembly, 
as shown above. 



Figure 2. Assembler Macros 



INTRODUCTION Page 5 

Macro Assembler supports an expanded set of conditional 
directives. Directives for evaluating a variety of assembly 
conditions can test assembly results and branch where 
required. Unneeded or unwanted portions of code will be 
left unassembled. Macro Assembler can test for blank or 
nonblank arguments, for defined or undefined symbols, for 
equivalence, for first assembly pass or second, and can 
compare strings for identity or difference. The conditional 
directives simplify the evaluation of assembly results, and 
make programming the testing code for conditions easier. 

Macro Assembler's conditional assembly facility also 
supports conditionals inside conditionals ("nesting"). 
Conditional assembly blocks can be nested up to 255 levels. 
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If condition 
is truer IF 
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assembles en- 
tire condi- 
tional block. 
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Figure 3. Conditional Statements 
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Macro Assembler supports all the major 8080 directives found 
in Microsoft's Macro Assembler for the 8080 processor. This 
means that any conditional, macro, or repeat blocks 
programmed under the 8080 Macro Assembler can be used under 
Macro Assembler for the 8086. Processor instructions and 
some directives (e.g., .PHASE, CSEG, DSEG) within the blocks 
will need to be converted to the 8086 instruction set. All 
the major Macro Assembler directives (pseudo-ops) for the 
8080 that are supported under Macro Assembler for the 8086 
will assemble as is, as long as the expressions to the 
directives are correct for the processor and the program. 
The syntax of directives is unchanged. Macro Assembler is 
upwardly-compatible, Macro Assembler for the 8080 processor 
and with Intel's ASM86 (R) , except Intel codemacros and 
macros. 



Some 8086 instructions take only one operand type. If a 
typeless operand is entered for an instruction that accepts 
only one type of operand (e.g., in the instruction PUSH 
IBX] , (BX] has no size, but PUSH only takes a word) , it 
would be wasteful to return an error for a lapse of memory 
or a typographical error. When the wrong type choice is 
given. Macro Assembler displays an error message but 
generates the "correct" code. That is, it always outputs 
instructions, not just NOP instructions. For example, if 
you enter: 

MOV AL,WORDLBL 



You may have 
meant one of 
three instructions: 




\^ 



(2) 

MOV AL,BYTE PTR WORDLBL 
(3) 
MOV AL,<other> 



MOV AX, WORDLBL 



Macro Assembler generates instruction (2) because it assumes 
that when you specify a register, you mean that register and 
that size; therefore, the other operand is the "wrong 
size." Macro Assembler accordingly modifies the "wrong" 
operand to fit the register size (in this case) or the size 
of whatever is the most likely "correct" operand in an 
expression. This eliminates some mundane debugging chores. 
An error message is still returned, however, because you may 
have misstated the operand the Macro Assembler assumes is 
"correct. " 
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Overview o£ Macro Assembler Operation 

The first task in developing a program is to create a source 
file. Use EDLIN (the resident editor in Microsoft's MS-DOS 
operating system) , or any other 8086 editor compatible with 
your operating system, to create the Macro Assembler source 
file. Macro Assembler assumes a default filename extension 
of .ASM for the source file. Creating the source file 
involves creating instruction and directive statements that 
follow the rules and constraints described in Chapters 1-4 
in this manual. 

When the source file is ready, run Macro Assembler as 
described in Chapter 5, "Assembling a Macro Assembler Source 
File." Refer to Chapter 7, "Macro Assembler Messages," for 
explanations of any messages displayed during or immediately 
after assembly. 
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Figure 4. Overview of Macro Assembler Operation 
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Macro Assembler is a two-pass assembler. This means that 
the source file is assembled twice. But slightly different 
actions occur during each pass. During the first pass, the 
assembler: 

evaluates the statements and expands macro call 
statements 

calculates the amount of code it will generate 

builds a symbol table where all symbols, variables, 
labels, and macros are assigned values 

During the second pass, the assembler 

fills in the symbol, variable, label, and 
expression values from the symbol table 

expands macro call statements 

emits the relocatable object code into a file with 
the default filename extension .OBJ 

The .OBJ file is suitable for processing with the Microsoft 
LINK utility (MS-LINK). The .OBJ file can be stored as part 
of the user's library of object programs, which later can be 
linked with one or more .OBJ modules by MS-LINK (refer to 
the MS-LINK utility for further explanation and 
instructions) . The .OBJ modules can also be processed with 
the Microsoft LIB Library Manager (refer to the Mi crosof t 
LIB L ibrary Manager Manual for further explanation an"3 
instructions) . 

The source file can also be assembled without creating an 
.OBJ file. All the other assembly steps are performed, but 
the object code is not sent to disk. Only erroneous source 
statements are displayed on the terminal screen. This 
practice is useful for checking the source code for errors. 
It is faster than creating an .OBJ file because no file is 
created or written. Modules can be test assembled quickly 
and errors corrected before the object code is put on disk. 
Modules that assemble without errors do not clutter the 
disk. 
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Figure 5. Pass 1 and Pass 2 
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The cross-reference file contains a compact representation 
of variables, labels, and symbols. The cross-reference file 
receives the default filename extension .CRF. When this 
cross-reference file is processed by Microsoft CREF 
(MS-CREF) , the file is converted into an expanded symbol 
table that lists all the variables, labels, and symbols in 
alphabetical order; followed by the line number in the 
source program where each is defined; followed by the line 
numbers where each is used in the program. The final 
cross-reference listing receives the filename extension 
.REF. (Refer to the Microsoft CREF Cross-Reference Utility 
Manual for further explanation and instructions.) 
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Figure 6. Files That Macro Assembler Produces 
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CHAPTER 1 
CREATING A MACRO ASSEMBLER SOURCE FILE 



To create a source file for Macro Assembler, you need to use 
an editor program, such as EDLIN in Microsoft's MS-DOS. You 
simply create a program file as you would for any other 
assembly or high-level programming language. Use the 
general facts and specific descriptions in this chapter and 
the three following chapters when creating the file. 

This chapter discusses the statement format and introduces 
descriptions of its components. In Chapter 2, you will find 
full descriptions of names: variables, labels, and symbols. 
Chapter 3 provides full descriptions of expressions and 
their components, operands and operators. Chapter 4 
includes full descriptions of the assembler directives. 



1.1 GENERAL FACTS ABOOT SOURCE FILES 

Naming Your Source File 

When you create a source file, you must name it. A filename 
may be any name that is legal for your operating system. 
When you run Macro Assembler to assemble your source file. 
Macro Assembler assumes that your source filename has the 
extension .ASM. 

You do not need to give your source filename the .ASM 

extension. However, if your source filename has has an 

extension other than .ASM, you nwst specify the extension 
name when you run Macro Asseitbler. (You do not need to 

specify the .ASM extension if your source filename has an 

extension of .ASM. Macro Assembler will supply the default 
extension for you.) 
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Note that Macro Assembler gives the object file it outputs 
the default extension .OBJ. To avoid confusion or the 
destruction of your source file, you should avoid giving a 
source file an extension of .OBJ. For similar reasons, you 
should also avoid the extensions .EXE, .LST, .CRF, and .REF. 

Legal Characters 

The legal characters for your symbol names are: 

A-Z 0-9 ? @ _ $ 

Only the numerals (0-9) cannot appear as the first character 
of a name (a numeral must appear as the first character of a 
numeric value) . 

Additional special characters act as operators or 
delimiters: 

: (colon) — segment override operator 

(period) — operator for field name of Record or 
Structure; may be used in a filename only if 
it is the first character 

[ ] (square brackets — around register names to 
indicate value in address in register, not 
value (data) in register 

( ) (parentheses) — operator in DUP expressions and 
operator to change precedence of operator 
evaluation 

< > (angle brackets) operators used around 
initialization values for Records or Structure, 
around parameters in IR^ macro blocks, and to 
indicate literals 

The square brackets and angle brackets are also 
used for syntax notation in the discussions of the 
assembler directives (Section 4.2, "Directives"). 
When these characters are operators and not syntax 
notation, you are told explicitly; for example, 
"angle brackets must be coded as shown." 
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Nuneric Notation 

The default input radix for all numeric values is decimal. 
The output radix for all listings is hexadecimal for code 
and data items and decimal for line numbers. The output 
radix can only be changed to octal radix by giving the /O 
switch when Macro Assembler is run (see Section 5.4, "Macro 
Assembler Command Switches"). There are two ways to change 
the input radix: 



1. With the .RADIX directive (see Section 4.2.1, 
"Memory Directives") 

2. By special notation appended to a numeric value: 
Radix Range Notation Example 



Binary 


0-1 


B 


OlllOlOOB 


Octal 


0-7 


Q or 


735Q or 6210 


Decimal 


0-9 


none or D 


9384 (default) 
8149D* 


Hexadecimal 


0-9 
A-F 


H 


OPFH or BOH** 



* When .RADIX directive changes default radix to not 

decimal. 

**First character must be numeral from 0-9. 
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ffhat's in a Source File? 

A source file for Macro Assembler consists of instruction 
statements and directive statements. Instruction statements 
are made of 8086 instruction mnemonics and their operands, 
which command specific processes directly to the 8086 
processor. Directive statements are commands to Macro 
Assembler to prepare data for use in and by instructions. 

Statement line format is described in Section 1.2. The 
parts of a statement are described in Sections 1.3-1.6 and 
in Chapters 2-4. Statements are usually placed in blocks of 
code assigned to a specific segment (code, data, stack, 
extra) . The segments may appear in any order in the source 
file. Within the segments, generally speaking, statements 
may appear in any order that creates a valid program. Some 
exceptions to random ordering do exist, which will be 
discussed under the affected assembler directives. 

Every segment must end with an end segment statement (ENDS) ; 
every procedure must end with an end procedure statement 
(ENDP) ; and every structure must end with an end structure 
statement (ENDS). Likewise, the source file must end with 
an END statement that tells Macro Assembler where program 
execution should begin. 

( 
Section 3.1, "Memory Organization," describes how segments, V^ 

groups, the ASSUME directive, and the SEG operator relate to 

one another and to your programming as a whole. This 

information is important and helpful for developing your 

programs. The information is presented in Chapter 3 as a 

prelude to the discussion of operands and operators. 
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1.2 STATEMENT LINE FORMAT 

Statements in source files follow a strict format, which 
allows some variation. 

Macro Assembler directive statements consist of four 
"fields": Name, Action, Expression, Comment. For example: 

FOO DB- 0D5E ; create variable FOO 

;containing the value 0D5EH 

III 
Name Action Expression ;Comment 

Macro Assembler instruction statements usually consist of 
three "fields": Action, Expression, Comment. For example: 

MOV CX,FOO ; here's the count number 

I I . I 

Action Expression ;Comment 

An instruction statement may have a Name field under certain 
circumstances; see the discussion in Section 1.3, "Names." 
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1.3 NAMES 



The name field, when present, is the first entry on the 
statement line. The name may begin in any column, although 
normally names are started in column 1. 

Names may be any length you choose. However, Macro 
Assembler considers only the first 31 characters significant 
when your source file is assembled. 

One other significant use for names is with the MACRO 
directive. Although all the rules covering names, described 
in Chapter 2, apply to MACRO names, the discussion of macro 
names is better left to the section describing the macro 
facility. 



Macro Assembler supports the use of names in a statement 
line for three purposes: to represent code, to represent 
data, and to represent constants. 

To make a name represent code, use: 

NAME: followed by a directive, instruction, or 

nothing at all 
NAME LABEL NEAR (for use inside its own segment 

only) 

NAME LABEL FAR (for use outside its own segment) 

EXTRN NAMEtNEAR (for use outside its own module but 
inside its own segment only) 

EXTRN NAME: FAR (for use outside its own module and 
segment) 

To make a name represent data, use: 

NAME LABEL <size> (BYTE, WORD, etc.) 

NAME Dx <exp> 

EXTRN NAME:<size> (BYTE, WORD, etc.) 
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To make a name represent a constant, use: 
NAME EQU <constant> 
NAME = <constant> 
NAME SEGMENT <attributes> 
NAME GROUP <segment-names> 
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1.4 COMNEUrS 



Comments are never required for the successful operation of 
an assembly language program, but they are strongly 
recommended. 

If you use comments in your program, every comment on every 
line must be preceded by a semicolon. If you want to place 
a very long comment in your program, you can use the COMMENT 
directive. The COMMENT directive releases you from the 
required semicolon on every line (refer to COMMENT in 
Section 4.2.1, "Memory Directives"), 

Comments document the processing that is supposed to happen 
at a particular point in a program. When comments are used 
in this manner, they can be useful for debugging, for 
alteripg code, or for updating code. Consider putting 
comments at the beginning of each segment, procedure, 
structure, module, and after each line in the code that 
begins a step in the processing. 

Comments are ignored by Macro Assembler. Comments do not 
add to the memory required to assemble or to run your 
program, except in macro blocks where comments are stored 
with the code. 
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1.5 ACTION 



The action field contains either an 8086 instruction 
mnemonic or a Macro Assembler assembler directive. Refer to 
Section 4.1, "Instructions," for a general discussion and to 
Appendix C for a list of 8086 instruction mnemonics. The 
Macro Assembler directives are described in detail in 
Section 4.2, "Directives." 

If the name field is blank, the action field will be the 
first entry in the statement format. In this case, the 
action may appear in any column, 1 through maximum line 
length (minus columns for action and expression) . 

The entry in the action field either directs the processor 
to perform a specific function or it directs the assembler 
to perform one of its functions. Instructions tell the 
processor to perform some action. An instruction may have 
the data and/or addresses it needs built into it, or data 
and/or addresses may be found in the expression part of an 
instruction. For example: 



opcode I I operand I I data 



data 



I opcode I [operand I I addr I | addr I 
supplied supplied or found 



supplied s part of the instruction 

found s assembler inserts data and/or address ' from the 
information provided by expression in instruction 
statements 



(opcode is the action part of an instruction) 

Directives give the assembler directions for I/O, memory 
organization, conditional assembly, listing and 
cross-reference control, and definitions. 
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1.6 EXPRESSIONS 

The expression field contains entries which are operands 
and/or combinations of operands and operators. 

Some instructions take no operands; some take one, and 
others take two. For two-operand instructions, the 
expression field consists of a destination : operand and a 
source operand, in that order, separated by a comma. For 
example: 



opcode I Idest-operand | , | source-operand 



For one-operand instructions, the operand is a source or a 
destination operand, depending on the instruction. If one 
or both of the operands is omitted, the instruction carries 
that information in its internal coding. 

Source operands are immediate operands, register operands, 
memory operands, or attribute operands. Destination 
operands are register operands and memory operands. 



For directives, the expression field usually consists of 
single operand. For example: 



directive 



operand 



A directive operand is a data operand, a code (addressing) 
operand, or a constant, depending on the nature of the 
directive. 



For many instructions and directives, operands may be 
connected with operators to form a longer operand that looks 
like a mathematical expression. These operands are called 
complex operands. Use of a complex operand permits you to 
specify addresses or data derived from several places. For 
example: 

MOV F00[BX1,AL 
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The destination operand is the result of adding the address 
represented by the variable FOO and the address found in 
register BX. The processor is instructed to move the value 
in register AL to the destination calculated from these two 
operand elements. Another example: 

MOV AX,F00+5[BX] 

In this case, the source operand is the result of adding the 
value represented by the symbol FOO plus 5 plus the value 
found in the BX register. 
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Macro Assembler supports the following operands and 
operators in the expression £ield (shown in order of 
precedence) : 



Operands 



Operators 



Inunediate 

(incl. symbols) 
Register 
Memory 
label 
variables 
simple 
indexed 
structures 
Attribute 
override 
PTR 
: (seg) 
SHORT 
HIGH 
LOW 
value returning 
OFFSET 
SEG 
THIS 
TYPE 
.TYPE 
LENGTH 
SIZE 
record specifying 
FIELD 
MASK 
WIDTH 



LENGTH, SIZE, WIDTH, MASK, 
FIELD II, ( ), < > 

segment override (:) 

PTR, OFFSET, SEG, TYPE, THIS 

HIGH, LOW 

*, /, MOD, SHL, SHR 

+, -(unary), -(binary) 

EQ, NE, LT, LE, GT, GE 

NOT 

AND 

OR, XOR 

SHORT , .TYPE 



NOTE 

Some operators can be used as operands or as 
part of an operand expression. Refer to 
Sections 3.2, "Operands," and 3.3, "Operators," 
for details of operands and operators. 
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CHAPTER 2 
NAMES: LABELS, VARIABLES, AMD SYMBOLS 



Names are used in several ways throughout Macro Assembler, 
wherever any naming is allowed or required. 

Names are symbolic representations of values. The values 
may be addresses, data, or constants. 

Names may be any length you choose. However, Macro 
Assembler will truncate names longer than 31 characters when 
your source file is assembled. 

Names may be defined and used in a number of ways. This 
chapter introduces you to the basic ways to define and use 
names. You will discover additional uses as you study the 
chapters on Expressions and Action, and as you use Macro 
Assembler. 

Macro Assembler supports three types of names in statement 
lines: labels, variables, and symbols. This chapter covers 
how to define and use these three types of names. 
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2.1 LABELS 

Labels are names used as targets for JMP, CALL, and LOOP 
instructions. Macro Assembler assigns an address to each 
label as it is defined. When you use a label as an operand 
for JMP, CALL, or LOOP, Macro Assembler can substitute the 
attributes of the label for the label name, sending 
processing to the appropriate place. 

Labels are defined in one of four ways: 

1. <name>: 

Use a name followed* immediately by a colon. This 
defines the name as a NEAR label. <name>: may be 
prefixed to any instruction and to all directives 
that allow a Name field. <name>: may also be 
placed on a line by itself. 

Examples: 

CLEAR_SCREEN : MOV AL,20H 
FOO: DB OFH 
SUBR0UTINE3: 



2. <name> LABEL NEAR 
<name> LABEL FAR 

Use the LABEL directive. Refer to the discussion 
of the LABEL directive in Section 4.2.1, "Memory 
Directives." 

NEAR and FAR are discussed under the Type Attribute 
below. 

Examples: 

FOO LABEL* NEAR 
GOO LABEL FAR 



3. <name> PROC NEAR 
<name> PROC FAR 

Use the PROC directive. Refer to the discussion of 
the PROC directive in Section 4.2.1, "Memory 
Directives." 

NEAR is optional because it is the default if you 
enter only <name> PROC. NEAR and FAR are discussed 
under the Type Attribute below. 
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Examples: 

REPEAT PROC NEAR 

CHECKING PROC ;saine as CHECKING PROC NEAR 

FIND CHR PROC FAR 



4. EXTRN <naine>:NEAR 
EXTRN <name>:FAR 

Use the EXTRN directive. 

NEAR and FAR are discussed under the Type Attribute 
below. 

Ke£er to the discussion o£ the EXTRN directive in 
SQction 4.2.1, "Memory Directives." 

Examples: 

EXTRN FOO:NEAR 
EXTRN ZOO: FAR 



A label has four attributes: segment, offset, type, and the 
CS ASSUME in effect when the label is defined. Segment is 
the segment where the label is defined.' Offset is the 
distance from the beginning of the segment to the label's 
location. Type is either NEAR or FAR. 

Segment 

Labels are defined inside segments. The segment must be 
assigned to the CS segment register to be addressable. The 
segment may be assigned to a group, in which case the group 
must be addressable through CS. Macro Assembler requires 
that a label be addressable through the CS register. 
Therefore, the segment (or group) attribute of a symbol is 
the base address of the segment (or group) where it is 
defined. 



Offset 

The offset attribute is the number of bytes from the 
beginning of the label's segment to where the label is 
defined. The offset is a 16-bit unsigned number. 
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Type 

Labels are one of two types: NEAR or FAR. NEAR labels are 
used for references from within the segment where the label 
is defined. NEAR labels may be referenced from more than 
one module, as long as the references are from a segment 
with the same name and attributes and have the same CS 
ASSUME . 

FAR labels are used for references from segments with a 
different CS ASSUME, or when there are more than 64K bytes 
between the label reference and the label definition. 

NEAR and FAR cause Macro Assembler to generate slightly 
different code. NEAR labels supply their offset attribute 
only (a 2-byte pointer) . FAR labels supply both their 
segment and offset attributes (a 4-byte pointer). 
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2.2 VARIABLES 

Variables are names used in expressions as operands bo 
instructions and directives. A variable represents an 
address where a specified value may be found. 

Variables look much like labels and are defined alike in 
some ways. The differences are important. 

Variables are defined three ways: 

1. <name> <define-dir> ?no colon! 

<name> <struc-name> <expression> 
<name> <rec-name> <expression> 

<define-dir> is any of the five Define directives: 
DB, DW, DD, DQ, DT 

Example: 

START_MOVE DW ? 

<struc-name> is a structure name defined by the 
STRUC directive. 

<rec-name> is a record name defined by the RECORD 
directive. 

Examples: 

CORRAL STRUC 



ENDS 
HORSE CORRAL < ' SADDLE ' > 

Note that HORSE will have the same size as the 
structure CORRAL. 



GARAGE RECORD CAR:8='P' 

SMALL GARAGE 10 DUP(<*Z'>) 

Note that SMALL will have the same size as the 
record GARAGE. 

See the DEFINE, STRUC, and RECORD directives in 
Section 4.2.1, "Memory Directives." 

<name> LABEL <size> 

Use the LABEL directive with one of the size 
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specifiers. 

<size> is one of the following size specifiers: 

BYTE - specifies 1 byte 
WORD - specifies 2 bytes 
DWORD - specifies 4 bytes 
QWORD - specifies 8 bytes 
TBYTE - specifies 10 bytes 

Example: 

CURSOR LABEL WORD , 

See LABEL directive in Section 4.2.1, "Memory 
Directives." 

3. EXTRN <name>:<size> 

Use the EXTRN directive with one of the size 
specifiers described above. See EXTRN directive in 
Section 4.2.1, "Memory Directives." 

Example: 

EXTRN FOO: DWORD 



Variables also have the three attributes segment, offset, 
and type (as do labels) . 

Segment and Offset are the same for variables as for labels. 
The Type attribute is different. 



Type 

The type attribute is the size of the variable's location, 
as specified when the variable is defined. The size depends 
on which Define directive was used or which size specifier 
was used to define the variable. 



Directive 


Type 


Size 


DB 


BYTE 


1 byte 


DW 


WORD 


2 bytes 


DD 


WORD 


4 bytes 


DQ 


QWORD 


8 bytes 


DT 


TBYTE 


10 bytes 
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2 . 3 SYMBOLS 

Symbols are names defined without reference to a Define 
directive or to code. Like variables, symbols are also used 
in expressions as operands to instructions and directives. 

Symbols are defined three ways: 

1. <name> EQU <expression> 

Use the EQU directive. See EQU directive in 
Section 4.2.1, "Memory Directives." 

<expression> may be another symbol, an instruction 
mnemonic, a valid expression, or any other entry 
(such as text or indexed references) . 



iples: 






FOO 


EQU 


7H 


ZOO 


EQU 


FOO 



<name> = <expression> 

Use the equal sign directive. See Equal Sign 
directive in Section 4.2.1, "Memory Directives." 

<expression> may be any valid expression. 

Examples: 



GOO 


= 


OFH 


GOO 


= 


$+2 


GOO 


= ' 


GOO+FOO 



EXTRN <name>:ABS 

Use the EXTRN directive with type ABS. See EXTRN 
directive in Section 4.2.1, "Memory Directives." 

Example: 

EXTRN BAZ:ABS 

BAZ must be defined by an EQU or « directive to a 
valid expression. 
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CHAPTER 3 
EXPRESSIONS: OPERANDS AND OPERATORS 



Chapter 1 provided a brief introduction to expressions. 
Basically, expression is the terra used to indicate values on 
which an instruction or directive performs its functions. 

Every expression consists of at least one operand (a value) . 
An expression may consist of two or more operands. Multiple 
operands are joined by operators. The result is a series of 
elements that looks like a mathematical expression. 

This chapter describes the types of operands and operators 
that Macro Assembler supports. The discussion of memory 
organization in a Macro Assembler program acts as a preface 
to the descriptions of operands and operators, and as a link 
to topics discussed in Chapter 2. 
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3.1 MEMORY ORGAHIZATIOR 

Most of your assembly language program is written in 
segments. In the source file, a segment is a block of code 
that begins with a SEGMENT directive statement and ends with 
an ENDS directive. In an assembled and linked file, a 
segment is any block of code that is addressed through the 
same segment register and is not more than 64K bytes long. 

You should note that Macro Assembler leaves everything 
relating to segments to MS-LINK, MS-LINK resolves all 
references. For that reason. Macro Assembler does not check 
(because it cannot) to see if your references are entered 
with the correct distance type. Values such as OFFSET are 
also left to MS-LINK to resolve. 

Although a segment may not be more than 64K bytes long, you 
may, as long as you observe the 64K limit, divide a segment 
among two or more modules. (The SEGMENT statement in each 
module must be the same.) 

When the modules are linked together, the several segments 
become one. References to labels, variables, and symbols 
within each module acquire the offset from the beginning of 
the whole segment, not just from the beginning of their 
portion of the whole segment. (All divisions are removed.) 

You have the option of grouping several segments into a 
group using the GROUP directive. When you group segments, 
you tell Macro Assembler that you want to be able to refer 
to all of these segments as a single entity. (This does not 
eliminate segment identity, nor does it make values within a 
particular segment less immediately accessible. It does 
make value relative to a group base.) The advantage of 
grouping is that you can refer to data items without 
worrying about segment overrides or changing segment 
registers. 

With this in mind, you should note that references within 
segments or groups are relative to a segment register. 
Thus, until linking is completed, the final offset of a 
reference is relocatable. For this reason, the OFFSET 
operator does not return a constant. The major purpose of 
OFFSET is to cause Macro Assembler to generate an immediate 
instruction; that is, to use the address of the value 
instead of the value itself. 
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There ace two kinds o£ references in a program: 

1. Code references - JMP, CALL, LOOPxx - These 
references are relative to the address in the CS 
register. (You cannot override this assignment.) 

2. Data references - all other references - These 
references are usually relative to the DS register, 
but this assignment may be overridden. 

When you give a forward reference in a program statement, 
for example: 

MOV AX,<ref> 

Macro Assembler first looks for the segment of the 
reference. Macro Assembler scans the segment registers for 
the SEGMENT of the reference, then the GROUP (if any) of the 
reference. 

However, the use of the OFFSET operator always returns the 
offset relative to the segment. If you want the offset 
relative to a GROUP, you must override this restriction by 
using the GROUP name and the colon operator. For Example: 

MOV AX, OFFSET <group-name>: <ref > 

If you set a segment register to a group with the ASSUME 
directive, then you may also override the restriction on 
OFFSET by using the register name. For example: 

MOV AX, OFFSET DS:<ref> 

The result of both of these statements is the same. " 

Code labels have four attributes: 

1. Segment - what segment the label belongs to 

2. Offset - the number of bytes from the beginning of 
its segment 

3. Type - NEAR or PAR 

4. CS ASSUME - the C% ASSUME the label was coded under 

When you enter a NEAR JMP or NEAR CALL, you are changing the 
offset (IP) in CS. Macro Assembler compares the CS ASSUME 
of the target (where the label is defined) with the current 
CS ASSUME. If they are different. Macro Assembler returns 
an error (you must use a FAR JMP or FAR CALL) . 
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When you enter a FAR JMP or. FAR CALL, you are changing both 
the offset (IP) in CS and the paragraph number. The 
paragraph number is changed to the CS ASSUME of the target 
address. 

Let's take a common case, a segment called CODE, and a group 
(called DGROUP) that contains three segments (called DATA, 
CONST, and STACK). 

The program statements would be: 

DGROUP GROUP DATA, CONST, STACK 

ASSUME CS : CODE, DS : DGROUP ,SS :DGROUP,ES : DGROUP 
MOV AX, DGROUP ;CS initialized by entry; 
MOV DS,AX ;you initialize DS, do this 

•as soon as possible, 
; especially before any 
;DS relative references 



As a diagram, 
follows: 



this arrangement could be represented as 



CODE 



-CS 



DATA 



■DS,ES,SS 



<64K 



CON ST 



STACK 
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Given this arrangement, a statement like 

MOV AX,<variable> 

causes Macro Assembler to find the best segment register to 
reach this variable. (The "best" register is the one that 
requires no segment overrides.) 

A statement like 

MOV AX, OFFSET <variable> 

tells Macro Assembler to return the offset of the variable 
relative to the beginning of the variable's segment. 

If this <variable> is in the CONST segment and you want to 
reference its offset from the beginning of DGROUP, you need 
a statement like the following: 

MOV AX, OFFSET DGROUP: <variable> 

Macro Assembler is a two-pass assembler. During pass 1, it 
builds a symbol table and calculates how much code is 
generated, but does not produce object code. If undefined 
items are found (including forward references) , assumptions 
are made about the reference so that the correct number of 
bytes are generated on pass 1. Only certain types of errors 
are displayed: errors involving items that must be defined 
on pass 1. No listing is produced unless a /D switch is 
given when you run the assembler. The /D switch produces a 
listing for both passes. 

On pass 2, the assembler uses the values defined in pass 1 
to generate the object code. Definitions of references 
during pass 2 are checked against the pass 1 value, which is 
in the symbol table. Also, the amount of code generated 
during pass 1 must match the amount generated during pass 2. 
If either is different. Macro Assembler returns a phase 
error . 

Because pass 1 must keep correct track of the relative 
offset, some references must be known on pass 1. If they 
are not known, the relative offset will not be correct. 

The following references must be known on pass 1: 

1. IF/IFE <expression> 

If <expression> is ' not known on pass 1, Macro 
Assembler does not know to assemble the conditional 
block (or which part to assemble if ELSE is used) . 
On pass 2, the assembler would know and would 
assemble, resulting in a phase error. 
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2. <expression> DUP(...) 

This operand explicitly changes the relative 
offset, so <expression> must be known on pass 1. 
The value in parentheses need not be known because 
it does not affect the number of bytes generated. 

3. .RADIX <expression> 

Because this directive changes the input radix, 
constants could have a different value, which could 
cause Macro Assembler to evaluate IF or DUP 
statements incorrectly. 

The biggest problem for the assembler is handling forward 
references. How can it know the kind of a reference when it 
still has not seen the definition? This is one of the main 
reasons for two passes. And, unless Macro Assembler can 
tell from the statement containing the forward reference 
what the size, the distance, or any other of its attributes 
are, the assembler can only take the safe route (generate 
the largest possible instruction in some cases, except for 
segment override or FAR) . This results in extra code that 
does "nothing. (Macro Assembler figures this out by pass 2, 
but it cannot reduce the size of the instructions without 
causing an error, so it puts out NOP instructions (90H) . 

For this reason, Macro Assembler includes a number of 
operators to help the assembler. These operators tell Macro 
Assembler what size instruction to generate when it is faced 
with an ambiguous choice. As a benefit, you can also reduce 
the size of your program by using these operators to change 
the nature of the arguments to the instructions. 
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Examples: 

MOV AXfFOO ;F00 = forward constant 

This statement causes Macro Assembler to generate a move 
from memory instruction on pass 1. By using the OFFSET 
operator, we can cause Macro Assembler to generate an 
immediate operand instruction. 

MOV AX, OFFSET FOO ;OFFSET says use the address 
;of FOO 

Because OFFSET tells Macro Assembler to use the address of 
FOO, the assembler knows that the value is immediate. This 
method saves a byte of code. 

Similarly, if you have a CALL statement that calls to a 
label that may be in a different CS ASSUME, you can prevent 
problems by attaching the PTR operator to the label: 

CALL FAR PTR <forward-label> 

At the opposite extreme, you may have a JMP forward that is 
less than 127 bytes. You can save yourself a byte if you 
use the SHORT operator. 

JMP SHORT <forward-label> 

However, you must be sure that the target is indeed within 
127 bytes or Macro Assembler will not find it. 

The PTR operator can be used another way to save yourself a 
byte when using forward references. If you defined FOO as a 
forward constant, you might enter the statement: 

MOV [EX] ,F00 

You may want to refer to FOO as a byte immediate. In this 
case, you could enter either of these statements (they are 
equivalent) : 

MOV BYTE PTR [BXl ,F00 

MOV [BX] ,BYTE PTR FOO 

These statements tell Macro Assembler that FOO is a byte 
immediate. A smaller instruction is generated. 
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3.2 OPERANDS 

An operand may be any one of three types: Immediate, 
Register, or Memory operands. There is no restriction on 
combining the types of operands. 

The following list shows all the types and the items that 
comprise them: 

Immediate operands 
Data items 
Symbols 

Register operands 

Memory operands 
Direct 

Labels 

Variables 

Offset (fieldname) 

Indexed 

Base register 
Index register 
[constant] 
^displacement 

Structure 
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3.2.1 Immediate Operands 

Inunediate operands are constant values that you supply when 
you type a statement line. The value may be typed either as 
a data item or as a symbol. 

Instructions that take two operands permit an immediate 
operand as the source operand only (the second operand in an 
instruction statement). For example: 

MOV AX, 9 



Data Items 

Macro Assembler recognizes values in forms other than 
decimal when special notation is appended. The default 
input radix is decimal. Any numeric values entered without 
numeric notation appended will be treated as a decimal 
value. These other values include ASCII characters as well 
as numeric values. 



Data Form 

Binary 

Octal 

Decimal 

Hexadecimal 
ASCII 

10 real 
16 real 



Format 

xxxxxxxxB 

XX xO 
xxxQ 

xxxxx 

XXXXXD 



xxxxR 



•xx 




"XX 


n 


XX. 


XXE&+XX 


X. . 


.XR 



Example 

OlllOOOlB 

7350 (letter 0) 
412Q 

65535 (default) 

lOOOD (when .RADIX changes input 
radix to nondecimal) 

OFFFFH (1st digit must be 0-9) 

'OM' (more than two with DB only; 
"OM" both forms are synonymous) 

25.23E-7 (floating point format) 

8F76DEA9R (1st digit must be 0-9; 
the total number of digits 
must be 8, 16, or 20; or 9, 
17, 21 if first digit is 0) 



Symbols 



Symbol names equated with some form of constant information 
(see Section 2.3, "Symbols") may be used as immediate 
operands. Using a symbol constant in a statement is the 
same as using a numeric constant. Therefore, using the 
sample statement above, you could type: 
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MOV AX,FOO 
assuming FOO was defined as a constant symbol. For example: 
FOO EQU 9 



3.2.2 Register Operands 

The 8086 processor contains a number of registers. These 
registers are identified by two-letter symbols that the 
processor recognizes (the symbols are reserved). 

The registers are appropriated to different tasks: general 
registers, pointer registers, counter registers, index 
registers, segment registers, and a flag register. 

The general registers are two sizes: 8-bit and 16-bit. All 
other registers are 16-bit. 

The general registers are both 8-bit and 16-bit registers. 
Actually, the 16-bit general registers are composed of a 
pair of 8-bit registers, one for the low byte (bits 0-7) and 
one for the high byte (bits 8-15)". Note, however, that each 
8-bit general register can be used independently from its 
mate. In this case, each 8-bit register contains bits 0-7. 

Segment registers are initialized by the user and contain 
segment base values. The segment register names (CS , DS , 
SS, BS) can be used with the colon segment override operator 
to inform Macro Assembler that an operand is in a different 
segment than specified in an ASSUME statement. (See the 
segment override operator in Section 3.3.1, "Attribute 
Operators. ) " 

The flag register is one 16-bit register containing nine 
1-bit flags (six arithmetic flags and three control flags) . 

Each of the registers (except segment registers and flags) 
can be an operand in arithmetic and logical operations. 
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Register/Memory Field Encoding: 



M0D=11 


R/M 


W=0 


W=l 


000 


AL 


AX 


001 


CL 


CX 


010 


DL 


DX 


Oil 


BL 


BX 


100 


AH 


SP 


101 


CH 


BP 


110 


DH 


SI 


111 


BH 


DI 



Register Mode 



EFFECTIVE ADDRESS CALCULATION 


R/M 


MOD=00 


MOD=01 


MOD=10 


000 


[BX]+[SI1 


[BX]+[SI]+D8 


[BX]+[SI]+D16 


001 


.[BX1 + [DI] 


[BX]+[DI]+D8 


[BX]+[DI]+D16 


010 


(BP]+[SI] 


[BP]+[SI]+D8 


[BP]+[SI]+D16 


Oil 


[BP]+[DI] 


[BP]+[DI]+D8 


[BP]+[DI]+D16 


100 


[SI] 


[SI]+D8 


[SI]+D16 


101 


[DI] 


[DI]+D8 


[DI]+D16 


110 


DIRECT ADDRESS 


[BP]+D8 


[BP]-f-Dl6 


111 


[BX] 


[BX]+D8 


fBX]+Dl6 



Note: D8 = a byte value; D16 = a word value 



Other Registers: 

SegmenttCS 
DS 
SS 
ES 

Flags: 



code segment 
data segment 
stack segment 
extra segment 



1-bit 


arithmetic flags 


3 1- 


-bit control 


flags 


CF 


carry flag 


DF 


direction 


flag 


PF 


parity flag 


IF 


interrupt- 
flag 


■enable 


AF 


auxiliary flag 


TF 


trap flag 




ZF 


zero flag 








SF 


sign flag 
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NOTE 

The BX, BP, SI, and DI 
registers are also used as 
memory operands. The 
distinction is: when these 
registers are enclosed in 
square brackets [ 1 , they are 
memory operands; when they 
are not enclosed in square 
brackets, they are register 
operands (see Section 3.2.3, 
"Memory Operands'*). 
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3.2.3 Memory Operands 

A memory operand represents an address in memory. When you 
use a memory operand, you direct Macro Assembler to an 
address to find some data or instruction. 

A memory operand always consists of an offset from a base 
address. 

Memory operands fit into three categories: those that do 
not use a register (direct memory operands) , those that use 
a base or index register (indexed memory operands) , and 
structure operands. 



Direct Memory Operands 

Direct memory operands do not use a register, and consist of 
a single offset value. Direct memory operands are labels, 
simple variables, and offsets. 

Memory operands can be used as destination operands as well 
as source operands for instructions that take two operands. 
For example: 

MOV AX,FOO 
MOV FOO,CX 
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Indexed Memory Operands 

Indexed memory operands use base and index registers, 
constants, displacement values, and variables, often in 
combination. When you combine indexed operands, you create 
an address expression. 

Indexed memory operands use square brackets to indicate 
indexing (by a register or by registers) or subscripting 
(for example, FOOfS]). The square brackets are treated like 
plus signs (+) . Therefore, 

F00[51 is equivalent to FOO+5 
5[F001 is equivalent to 5+FOO 

The only difference between square brackets and plus signs 
occurs when a register name appears inside the square 
brackets. Then, the operand is indexed. 

The types of indexed memory operands are: 

Base registers: [BX] (BP] 

BP has SS as its default segment register; 
all others have DS as default. 

Index registers: [DI] [SI] 

[constant! Immediate in square brackets [8] , [FOOJ 

+Displacement 8-bit or 16-bit value. 

Used only with another indexed operand. 



These elements may be combined in any order. The only 
restriction is that two base registers and two indexed 
registers cannot be combined: 

[BX+BP] ; illegal 
[SI+DI] ; illegal 

Some examples of indexed memory operand combinations: 

[BP+81 
[SI+BXl [4] 
16[DI+BP+3] 
8[F001-8 

More examples of equivalent forms: 

5[BX][SI1 
BX+51 [SIl 
[BX+SI+5) 
IBX]5[SI1 
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Structure Operands 

Structure operands take the form <variable>.<f ield>. 

<variable> is any name you give when coding a statement line 
that initializes a Structure field. The <variable> may be 
an anonymous variable, such as an indexed memory operand. 

<field> is a name defined by a DEFINE directive within a 
STRUC block. <field> is a typed constant. 

The period (.) must be included. 

Example: 

ZOO STRUC 
GIRAFFE DB ? 
ZOO ENDS 

LONG_NECK ZOO <16> 

MOV AL,LONG_NECK. GIRAFFE 

MOV AL, I BX] .GIRAFFE ;anonymous variable 

The use of structure operands can be helpful in stack 
operations. If you set up the stack segment as a structure, 
setting BP to the top of the stack (BP equal to SP) , then 
you can access any value in the stack structure by field 
name indexed through BP; for example: 

(BP).FLD6 







ai • 9, 


FLDl 




FLD3 


FLD2 


STRUC * 


FLD4 




FLD6 


FLD5 




FLD7 



-SP 
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This method makes all values on the stack available all the 
time, not just the value at the top. Therefore, this method 
makes the stack a handy place to pass parameters to 
subroutines. 
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3.3 OPERATORS 

An operator may be one of four types: attribute, 
arithmetic, relational, or logical. 

Attribute operators are used with operands to override their 
attributes, return the value of the attributes, or to 
isolate fields of records. 

Arithmetic, relational, and logical operators are used to 
combine or compare operands. 



3.3.1 Attribute Operators 

Attribute operators used as operands perform one of three 
functions: 

Override an operand's attributes 

Return the values of operand attributes 

Isolate record fields (record specific operators) 



The following list shows all the attribute operators by 
type: 

Override operators 
PTR 

colon (:) (segment override) 
SHORT 
THIS 
HIGH 
LOW 

Value returning operators 
SEG 
OFFSET 
TYPE 
.TYPE 
LENGTH 
SIZE 

Record specific operators 

Shift count (Field name) 

WIDTH 

MASK 
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Override Operators 

These operators are used to override the segment, offset, 
type, or distance of variables and labels. 



Pointer (PTR) 

<attribute> PTR <expression> 

The PTR operator overrides the type (BYTE, WORD, 
DWORD) or the distance (NEAR, FAR) of an operand. 

<attribute> is the new attribute; the new type or 
new distance. 

<expression> is the operand whose attribute is to 
be overridden. 

The most important and frequent use for PTR is to 
assure that Macro Assembler understands what 
attribute the expression is supposed to have. This 
is especially true for the type attribute. 
Whenever you place forward references in your 
program, PTR will make clear the distance or type 
of the expression. This way you can avoid phase 
errors. 

The second use of PTR is to access data by type 
other than the type in the variable definition. 
Most often this occurs in structures. If the 
structure is defined as WORD but you want to access 
an item as a byte, PTR is the operator for this. 
However, a much easier method is to enter a second 
statement that defines the structure in bytes, too. 
This eliminates the need to use PTR for every 
reference to the structure. Refer to the LABEL 
directive in Section 4.2.1, "Memory Directives." 

Examples: 

CALL WORD PTR [BX] [SIl 
MOV BYTE PTR ARRAY 

ADD BYTE PTR F00,9 
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Segment Override (:) (colon) 

<segment-register>: odd r ess-express ion> 
<segment-name> : <address-expression> 
<group-nanie> : <address-expression> 

The segment override operator overrides the assumed 
segment of an address expression (which may be a 
label., a variable, or other memory operand). 

The colon operator helps with forward references by 
telling the assembler to what a reference is 
relative (segment, group, or segment register) . 

Macro Assembler assumes that labels are addressable 
through the current CS register. Macro Assembler 
also assumes that variables are addressable through 
the current DS register, or possibly the ES 
register, by default. If the operand is in another 
segment and you have not alerted Macro Assembler 
through the ASSUME directive, you will need to use 
a segment override operator. Also, if you want to 
use a nondefault relative base (that is, not the 
default segment register) , you will need to use the 
segment override operator for forward references. 
Note that if Macro Assembler can reach an operand 
through a nondefault segment register, it will use 
it, but the reference cannot be forward in this 
case. 

<segment-register> is one of the four segment 
register names: CS , DS, SS , ES. 

<segment-name> is a name defined by the SEGMENT 
directive. 

<group-name> is a name defined by the GROUP 
directive. 

Examples: 

MOV AX,ES: [BX+SI] 

MOV CSEG:FAR_LABEL,AX 

MOV AX, OFFSET DGROUP: VARIABLE 
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SHORT 



SHORT <label> 



SHORT overrides NEAR distance attributes of labels 
used as targets for the JMP instruction. SHORT 
tells Macro Assembler that the distance between the 
JMP statement and the <label> specified as its 
operand is not more than 127 bytes either 
direction. 

The major advantage of using the SHORT operator is 
to save a byte. Normally, the <label> carries a 
2-byte pointer to its offset in its segment. 
Because a range of 256 bytes can be handled in a 
single byte, the SHORT operator eliminates the need 
for the extra byte (which would carry 00 or FF 
anyway). However, you must be sure that the target 
is within +127 bytes of the JMP instruction before 
using SHORT. 

Example: 

JMP SHORT REPEAT 



REPEAT : 
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THIS 



THIS <distance> 
THIS <type> 



The THIS operator creates an operand. The value of 
the operand depends on which argument you give 
THIS. 

The argument to THIS may be: 

1. A distance (NEAR or FAR) 

2. A type (BYTE, WORD, or DWORD) 

THIS <distance> creates an operand with the 
distance attribute you specify, an offset equal to 
the current location counter, and the segment 
attribute (segment base address) of the enclosing 
segment. 

THIS <type> creates an operand with the type 

attribute you specify, an offset equal to the 

current location counter, and the segment attribute 

(segment base address) of the enclosing segment. 

Examples: 

TAG EQU THIS BYTE same as TAG LABEL BYTE 

SPOT_CHECK = THIS NEAR same as 
SPOT CHECK LABEL NEAR 
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HIGH r LOW 



HIGH <expression> 
LOW <expression> 



HIGH and LOW are provided for 8080 assembly 
language compatibility. HIGH and LOW are byte 
isolation operators. 

HIGH isolates the high 8 bits of an absolute 16-bit 
value or address expression. 

LOW isolates the low 8 bits of an absolute 16-bit 
value or address expression. 

Examples: 

MOV AH, HIGH WORD_VALUE ;get byte with sign bit 

MOV ALrLOW OPFFFH 
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These operators return the attribute values of the operands 
that follow them but do not override the attributes. 

The value returning operators take labels and variables as 
^heir arguments. 

Because variables in Macro Assembler have three attributes, 
you need to use value returning operators to isolate single 
attributes, as follows: 

SE6 isolates the segment base address 
OFFSET isolates the offset value 
TYPE isolates either type or distance 
LENGTH and SIZE isolate the memory allocation 



SEG 

SEC <label> 
SEG <variable> 



SEG returns the segment value (segment . base 
address) of the segment enclosing the label or 
variable. 

Example: 

MOV AX, SEG VARIABLE_NAME 

MOV AX , <segment-var iable> : < var iable> 
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OFFSET 

OFFSET <label> 
OFFSET <variable> 



OFFSET returns the offset value of the variable or 
label within its segment (the number of bytes 
between the segment base address and the address 
where the label or variable is defined). 



OFFSET is chiefly used to tell the assembler 
the operand is an immediate operand. 



that 



NOTES 

OFFSET does not make the value a constant. 
Only MS-LINK can resolve the final value. 

OFFSET is not required with uses of the DW 
or DD directives. The assembler applies an 
implicit OFFSET to variables in address 
expressions following DW and DD. 



Example: 

MOV BX, OFFSET FOO 



If you use an ASSUME to GROUP, OFFSET will not 
automatically return the offset of a variable from 
the base address of the group. Rather, OFFSET will 
return the segment offset, unless you use the 
segment override operator (group-name version) . If 
the variable GOB is defined in a segment placed in 
DGROUP, and you want the offset of GOB in the 
group, you need to enter a statement like: 

MOV BX, OFFSET DGROUP: GOB 

You must be sure that the GROUP directive precedes 
any reference to a group name, including its use 
with OFFSET. 



EXPRESSIONS: OPERANDS AND OPERATORS Page 3-25 

TYPE 

TYPE <label> 
TYPE <variable> 

If the operand is a variable, the TYPE operator 
returns a value equal to the number of bytes of the 
variable type, as follows: 

BYTE a 1 

WORD = 2 

DWORD « 4 

QWORD = 8 

TBYTE = 10 . 

STRUC = the number of bytes declared by STRUC 

If the operand is a label, the TYPE operator 
returns NEAR (FPPFH) or PAR (PPFEH) . 

Examples : 
' MOV AX, (TYPE FOO BAR) PTR (BX+SI] 
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.TYPE 

.TYPE <variable> 

The .TYPE operator returns a byte that describes 
two characteristics of the <variable>: 1) the 
mode, and 2) whether it is External or not. The 
argument to .TYPE may be any expression (string, 
numeric, logical). If the expression is invalid, 
.TYPE returns zero. 

The byte that is returned is configured as follows: 

The lower two bits are the mode. If the lower two 
bits are: 

the mode is Absolute 

1 the mode is Program Related 

2 the mode is Data Related 

The high bit (80H) is the External bit. If the 

high bit is on, the expression contains an 

External. If the high bit is off, the expression 
is not External. 

The Defined bit is 20H. This bit is on if the 
expression is locally defined, and it is off if the 
expression is undefined or external. If neither 
bit is on, the expression is invalid. 

.TYPE is usually used inside macros, where an 
argument type may need to be tested to make a 
decision regarding program flow; for example, when 
conditional assembly is involved. 



Example: 




FOO 


MACRO X 




LOCAL Z 


Z 


.TYPE X 


IF 


Z... 



.TYPE tests the mode and type of X. Depending on 
the evaluation of X, the block of code beginning 
with IF Z... may be assembled or emitted. 
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LENGTH 

LENGTH <variable> 

LENGTH accepts only one variable as its argument. 

LENGTH returns the number of type units (BYTE, 
WORD, DWORD, QWORD, TBYTE) allocated for that 
variable. 

If the variable is defined by a DUP expression, 
LENGTH returns the number of type units duplicated; 
that is, the number that precedes the first DUP in 
the expression. 

If the variable is not defined by a DUP expression, 
LENGTH returns 1. 

Examples: 

FOO DW 100 DUP(l) 

MOV CX, LENGTH FOO ;get number of elements 
; in array 
; LENGTH returns 100 

BAZ DW 100 DUP (1,10 DUP(?)) 



LENGTH BAZ is still 100, regardless of the 
expression following DUP. 



GOO DD (?) 

LENGTH GOO returns 1 because only one unit is 
involved. 
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SIZE 

SIZE <variable> 

SIZE returns the total number of bytes allocated 
for a variable. 

SIZE is the product of the value of LENGTH times 
the value of TYPE. 

Example: 

FOO DW 100 DUP(l) 

MOV BXrSIZE FOO ;get total bytes in array 

SIZE = LENGTH X TYPE 

SIZE = 100 X WORD 

SIZE = 100 X 2 

SIZE = 200 
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Record Specific Operators 

Record specific operators are used to isolate fields in a 
record. 

Records are defined by the RECORD directive (see Section 
4.2.1, "Memory Directives"), A record may be up to 16 bits 
long. The record is defined by fields, which may be from 
one to 16 bits long. To isolate one of the three 
characteristics of a record field, you use one of the record 
specific operators, as follows: 

Shift count Number of bits from low end of record to low 
end of field (number of bits to right shift the 
record to lowest bits of record) 

WIDTH The number of bits wide the field or record is 
(number of bits the field or record contains) 

MASK Value of record if field contains its maximum 
value and all other fields are zero (all bits 
in field contain 1; all other bits contain 0) 



In the. following discussions of the record specific 
operators, the following symbols are used: 

FOO a record defined by the RECORD directive 
FOO RECORD FIELDl: 3,FIELD2: 6,FIELD3: 7 

BAZ a variable used to allocate FOO 
BAZ FOO < > 

FIELDl, FIELD2, and FIELD3 are the fields of the 
record FOO. 
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Shift-count - (record-fieldname) 

<record-f ieldnatne> 

The shift count is derived from the record 
fieldname to be isolated. 

The shift count is the number of bits the field 
must be shifted right to place the lowest bit of 
the field in the lowest bit of the record byte or 
word. 

If a 16-bit record (FOO) contains three fields 
(FlELDlr FIELD2, and FIELD3) , the record can be 
diagrammed as follows: 







1 1 1 


1 1 1 1 1 








WIDTH = 6 "^ 





FIELDl has a shift count of 13. 
FIELD2 has a shift count of 7. 
FIELD3 has a shift count of 0. 

When you want to isolate the value in one of these 
fields, you enter its name as an operand. 

Example: 

MOV DXrBAZ 
MOV CL,FIELD2 
SHR DX,CL 



FIELD2 is now right shifted, ready for access. 
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WIDTH 

WIDTH <record-f ieldnamo 
WIDTH <record> 

When a <record-f ieldnanie> is given as the argument, 
WIDTH returns the width of a record field as the 
number of bits in the record field. 

When a <record> is given as the argument, WIDTH 
returns the width of a record as the number of bits 
in the record. 

Using the diagram under shift count, WIDTH can be 
diagrammed as: 



I I I I I I I I I I M I I I 

PIELDl FIELD2 FIEL03 



The WIDTH of FIELDl equals 3, 
The WIDTH of FIELD2 equals 6, 
The WIDTH of FIELDS equals 7, 

Example: 

MOV CL, WIDTH FIELD2 



The number of bits in FIELD2 is now in the count 
register. 
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MASK 

MASK <record-£ieldname> 

MASK accepts a field name as its only argument. 

MASK returns a bit-mask defined by 1 for bit 
positions included by the field and for bit 
positions not included. The value return 
represents the maximum value for the record when 
the field is masked. 

Using the diagram used for shift count, MASK can be 
diagrammed as: 



olii 1 1 lliO 00 
1 F 8 



The MASK of FIELD2 equals 1F80H. 
Example; 



4-MASK 



MOV DXrBAZ 

AND DXrMASK FIELD 2 



FIELD2 is now isolated. 
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3.3.2 Arithmetic Operators 

Eight arithmetic operators provide the common mathematical 
functions (add, subtract, divide, multiply, modulo, 
negation) , plus two shift operators. 

The arithmetic operators are used to combine operands to 
form an expression that results in a data item or an 
address. 

Except for + and - (binary), operands must be constants. 

For plus (+) , one operand must be a constant. 

For minus (-) , the first (left) operand may be a 
nonconstant, or both operands may be nonconstants. The 
right must be a constant if the left is a constant. 



* Multiply 

/ Divide 

MOD Modulo. Divide the left operand by the right 

operand and return the value of the remainder 
(modulo) . Both operands must be absolute. 

Example: 

MOV AX, 100 MOD 17 

The value moved into AX will be OFH (decimal 
15). 

SHR Shift Right. SHR is followed by an integer 

which specifies the number of bit positions 
the value is to be shifted right. 

Example: 

MOV AX,1100000B SHR 5 

The value moved into AX will be IIB (03). 

SHL Shift Left. SHL is followed by an integer 

which specifies the number of bit positions 
the value is to be shifted left. 

Example: 

MOV AX, HOB SHL 5 

The value moved into AX will be OllOOOOOOB 
(OCOH) 
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- (Unary Minus) Indicates that following value is negative, 

as in a negative integer. 

+ Add. One operand must be a constant; one 

may be a nonconstant. 

- Subtract the right operand from the left 
operand. The first (left) operand may be a 
nonconstant, or both operands may be 
nonconstants. But the right may be a 
nonconstant only if the left is also a 
nonconstant and in the same segment. 



3.3.3 Relational Operators 

Relational operators compare two constant operands. 

If the relationship between the two operands matches the 
operator, FFFFH is returned. 

If the relationship between the two operands does not match 
the operator, a zero is returned. 

Relational operators are most .often used with conditional 
directives and conditional instructions to direct program 
control. 



EQ Equal. Returns true if the operands equal 

each other. 



NE Not Equal. Returns true if the operands are 

not equal to each other. 

LT Less Than. Returns true if the left operand 

is less than the right operand. 

LE Less than or Equal. Returns true if the left 

operand is less than or equal to the right 
operand. 



GT Greater Than. Returns true if the left 

operand is greater than the right operand. 

GE Greater than or Equal. Returns true if the 

left operand is greater than or equal to the 
right operand. 
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3.3.4 Logical Operators 

Logical operators compare two constant operands bitwise. 

LcJgical operators compare the binary values of corresponding 
bit positions of each operand to evaluate the logical 
relationship defined by the logical operator. 

Logical operators can be used two ways: 

1. To combine operands in a logical relationship. In 
this case, all bits in the operands will have the 
same value (either 0000 or FFFFH) . In fact, it is 
best to use these values for true (FFFFH) and false 
(0000) for the symbols you will use as operands, 
because in conditionals anything nonzero is true. 

2. In bitwise operations. In this case, the bits are 
different, and the logical operators act the same 
as the instructions of the same name. 



NOT Logical NOT. Returns true if left operand is 

true and right is false or if right is true 
and left is false. Returns false if both are 
true or both are false. 



AND Logical AND. Returns true if both operators 

are true. Returns false if either operator 
is false or if both are false. Both operands 
must be absolute values. 



OR Logical OR. Returns true if either operator 

is true or if both are true. Returns false 
if both operators are false. Both operands 
must be absolute values. 



XOR Exclusive OR. Returns true if either 

operator is true and the other is false. 
Returns false if both operators are true or 
if both operators are false. Both operands 
must be absolute values. 
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3.3.5 Expression Evaluation: Precedence Of Operators 

Expressions are evaluated higher precedence operators first, 
then left to right for equal precedence operators. 

Parentheses can be used to alter precedence. 

For example: 

MOV AX, 10 IB SHL 2*2 = MOV AX,00101000B 

MOV AX,101B SHL (2*2) = MOV AX,01010000B 

SHL and * are/ equal precedence. Therefore, their functions 
are performed in the order the operators are encountered 
(left to right) . 



Precedence of Operators 

All operators in a single item have the same precedence, 

regardless of the order listed within the item. Spacing and 

line breaks are used for visual clarity, not to indicate 
functional relations. 



1. LENGTH, SIZE, WIDTH, MASK 
Entries inside: parentheses { ) 

angle brackets < > 
square brackets ( 1 
Structure variable operand: <variable> .<f ield> 

2. Segment override operator: colon (:) 

3. PTR, OFFSET, SEG, TYPE, THIS 

4. HIGH, LOW 

5. *, /, MOD, SHL, SHR 

6. +, - (both unary and binary) 

7. EQ, NE, LT, LE, GT, GE 

8. Logical NOT 

9. Logical AND 

10. Logical OR, XOR 

11. SHORT,. TYPE 
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CHAPTER 4 
ACTION: INSTROCTIORS AMD DIRECTIVES 



The action field contains either an 8086 instruction 
mnemonic or a Macro Assembler assembler directive. 

Following a name field entry (if any) , action field entries 
may begin in any column. Specific spacing is not required. 
The only benefit of consistent spacing is improved 
readability. If a statement does not have a name field 
entry, the action field is the first entry. 

The entry in the action field either directs the processor 
to perform a specific function or directs the assembler to 
perform one of its functions. 
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4.1 INSTROCTIONS 

Instructions tell the command processor to perform some 
action. An instruction may have the data and/or addresses 
it needs built into it, or data and/or addresses may be 
found in the expression part of an instruction. For 
example: 



opcode 



opcode 



supplied 



operand 



operand 



data 



addr 



data 



addr 



supplied or Cound 



supplied = part of the instruction 

found = assembler inserts data and/or address from the 
information provided by expressions in instruction 
statements. 



(opcode equates to the binary code for 
of an instruction) 



the action 



Note that this manual does not contain detailed descriptions 
of the 8086 instruction mnemonics and their characteristics. 
For this, you will need to consult other texts. The 
following texts are recommended: 



1. Morse, Stephen P. The 80^86 Primer 
NJ: Hayden Publishing Co., 1980. 

2. Rector, Russell and George Alexy. The 8086 
Berkeley, CA: Osbourne/McGraw-Hill, 1980. 

3. The 8086 Family User's Ma nual . 
Intel Corporation, 1980. 



Rochelle Park, 

Book . 

Santa Clara, CA: 

Appendix C contains both an alphabetical listing and a 
grouped listing of the instruction mnemonics. The 
alphabetical listing shows the full name of the instruction. 
Following the alphabetical list is a list that groups the 
instruction mnemonics by the number and type of arguments 
they take. Within each group, the instruction mnemonics are 
arranged alphabetically. 
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4.2 DIRECTIVES 

Directives give the assembler directions and information 
about input and output, memory organization, conditional 
assembly, listing and cross-reference control, and 
definitions. 

The directives have been divided into groups by the function 
they perform. Within each group, the directives are 
described alphabetically. 

The groups are: 

Memory Directives 

Directives in this group are used to organize 
memory. Because there is no "miscellaneous" 
groupr the memory directives . group contains 
some directives that do not, strictly speaking, 
organize memory (for example, COMMENT). 

Conditional Directives 

Directives in this group are used to test 
conditions of assembly before proceeding with 
assembly of a block of statements. This group 
contains all of the IF (and related) 
directives. 

Macro Directives 

Directives in this group are used to create 
blocks of code called macros. This group also 
includes some special operators and directives 
that are used only inside macro blocks. The 
repeat directives are considered macro 
directives for descriptive purposes. 

Listing Directives 

Directives in this group are used to control 
the format and, to some extent, the content of 
listings that the assembler produces. 
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Appendix B contains a table of assembler directives, also 
grouped by function. Below is an alphabetical list of all 
the directives that Macro Assembler supports: 



ASSUME 


EVEN 


IRPC 


•RADIX 




EXITM 




RECORD 


COMMENT 


EXTERN 


LABEL 


REPT 


.CREF 




.LALL 






GROUP 


.LFCOND 


.SALL 


DB 




.LIST 


SEGMENT 


DD 


IF 




.SFCOND 


DQ 


IFB 


MACRb 


STRUC 


DT 


IFDEF 




SUBTTL 


DW 


IFDIF 


NAME 






IFE 




.TFCOND 


ELSE 


IFIDN 


ORG 


TITLE 


END 


IFNB 


%OUT 




ENDIF 


IFNDEF 




.XALL 


ENDM 




PAGE 


.XCREF 


ENDP 


IFl 


PROC 


.XLIST 


ENDS 


IF2 


PUBLIC 




EQU 


IRP 


PURGE 
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4.2.1 Meaory Directives 

ASSUME 

ASSUME <seg-reg> : <seg-name> [,...] 

or 

ASSUME NOTHING 

ASSUME tells the assembler that the symbols in the 
segment or group can be accessed using this segment 
register. When the assembler encounters a 
variable, it automatically assembles the variable 
reference under the proper segment register. You 
may enter from 1 to 4 arguments to ASSUME. 

The valid <seg-reg> entries are: 

CS, DS, ES, and SS. 

The possible entries for <seg-name> are: 

1. The name of a segment declared with the SEGMENT 
directive 

2. The name of a group declared with the GROUP 
directive 

3. An expression: either SEG <variable-name> or 
SEG <label-name> (see SEG operator. Section 
3.3) 

4. The key word NOTHING. ASSUME NOTHING cancels 
all register assignments made by a previous 
ASSUME statement 

If ASSUME is not used or if NOTHING is typed for 
<seg-name>, each reference to variables, symbols, 
labels, and so forth in a particular segment must 
be prefixed by a segment register. For example, 
type DS:FOO instead of simply POO. 

Example: 

ASSUME OS : DATA ,SS :DATA ,CS :CGROUP ,BS :NOTHING 
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COMMENT 

COMMENT<delim><text><delim> 

The £irst non-blank character encountered after 
COMMENT is the delimiter. The following <text> 
comprises a comment block which continues until the 
next occurrence of <delimiter>. 

COMMENT permits you to enter comments about your 
program without entering a semicolon (;) before 
each line. 

If you use COMMENT inside a macro block, the 
comment block will not appear on your listing 
unless you also place the .LALL directive in your 
source file. 

Example: 

Using an asterisk as the delimiter, the format of 
the comment block would be: 

COMMENT * 

any amount of text entered 

here as the comment block 

* ; return to normal mode 
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DEFINE BYTE 



DEFINE WORD 
define" DOUBLEWORD 
definj quadw ord 
define tenbytes" 



<varname> 


db 


<varnaine> 


dw 


<varname> 


dd 


<varname> 


DQ 


<varname> 


dt 



<exp> [ ,<exp>, 
<exp> t ,<exp> , 
' <exp> [ ,<exp>, 
<exp> ( ,<exp>, 
<exp> [ ,<exp> , 

The DEFINE directives are used to define variables 
or to initialize portions of memory. 

If the optional <varname> is entered, the DEFINE 
directives define the name as a variable. If 
<varname> has a colon, it becomes a NEAR label 
instead of a variable. (See also. Section 2.1, 
"Labels," and Section 2.2, "Variables.") 

The DEFINE directives allocate memory in units 
specified by the second letter of the directive 

(each DEFINE directive may allocate one or more of 

its units at a time): 

DB allocates one byte (8 bits) 
DW allocates one word (2 bytes) 
DD allocates two words (4 bytes) 
DQ allocates four words (8 bytes) 
DT allocates ten bytes 

<exp> may be one or more of the following: 

1. A constant expression 

2. The character ? for indeterminate 
initialization. Usually the ? is used to 
reserve space without placing any particular 
value into it. (It is the equivalent of the DS 
pseudo-op in MACRO-80) . 

3. An address expression (for DW and DD only) 

4. An ASCII string (longer than two characters for 
DB only) 

5. <exp>DUP(?) 

When this type of expression is the only 
argument to a define directive, the define 
directive produces an uninitialized data block. 
This expression with the ? instead of a value 
results in a smaller object file because only 
the segment offset is changed to reserve space. 



ACTION: INSTRUCTIONS AND DIRECTIVES 



Page 4-8 



<exp> DUP{ <exp> [,...] ) 

This expression, like item 5, produces a data 
block, but initialized with the value of the 
second <exp>. The first <exp> must be a 
constant greater than zero and must not be a 
forward reference. 



Example - Define Byte (DB) : 



NUM_BASE 
FILLER 



BUFFER 
TABLE 



NEW_PAGE 
ARRAY 



DB 
DB 



ONE_CHAR DB 
MULT CHAR DB 
MSG DB 



DB 
DB 



DB 
DB 



16 
? 

•M' 



; initialize with 

; indeterminate value 



'TOM JEROME EDWARD BOB DEAN* 

•MSGTEST* ,13,10 ;message, carriage return 
;and linefeed 

10 DUP(?) ; indeterminate block 

100 DUP(5 DUP(4) ,7) 

;100 copies of bytes 
;with values 4,4,4,4,4,7 

OCH ;form feed character 

1,2,3,4,5,6,7 



Example - Define Word (DW) : 



ITEMS 


DW 


SEGVAL 


DW 


BSIZE 


DW 


LOCATION 


DW 


AREA 


DW 


CLEARED 


DW 


SERIES 


DW 




; ti 
;2 


DISTANCE 


DW 



TABLE, TABLE+10,TABLE+20 

OFFFOH 

4 * 128 

TOTAL + 1 

100 DUP(?) 

50 DUP{0) 

2 DUP(2,3 DUP (BSIZE)) 
;two words with the byte values 
; 2, BSIZE, BSIZE, BSIZE, 2, BSIZE, BSIZE, BSIZE 

START TAB -ENDJTAB 
;difference oT two labels is a constant 
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Example - Define Doubleword (DD) 

TABLE 



DBPTR 



SEC PER DAY 



LIST 
HIGH 
FLOAT 



DD 



DD 

DD 
DD 
DD 



; 16-bit OFFSET, 

;then 16-bit 

;SE6 base value 
60*60*24 ;arithmetic is performed 

;by the assembler 
•XY' ,2 DUP(?) 
4294967295 ;raaximum 
6.735E2 ;floating point 



Example - Define Quadwocd (DQ) : 



LONGREAL 


DQ 


3.141597 


'decimal makes 
it real 


STRING 


DQ 


•AB' 


•no more than 2 
characters 


HIGH 


DQ 


18446744073709661615 ', 


maximum 


LOW 


DQ 


-18446744073709661615 , 


minimum 


SPACER 


DQ 


2 DUP(?) 


uninit .data 


FILLER 


DQ 


1 DUP(?,?) 


initalized w_/ 

indeterminate 

value 


HEX REAL 


DQ 


0FDCBA9A98765432105R 





Example - Define Tenbytes (DT) : 



ACCUMULATOR DT 


? 




STRING DT 


•CD* 


;no more than 2 
;characters 


PACKED DECIMAL DT 


1234567890 




FLOATING POINT DT 


3.1415926 
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END 

END [<exp>] 

The END statement specifies the end of the program. 

If <exp> is present r it is the start address of the 
program. If several modules are to be linked, only 
the main module may specify the start of the 
program with the END <exp> statement. 

If <exp> is not present, then no start address is 
passed to MS-LINK for that program or module. 

Example: 

END START ; START is a label somewhere in the 
; program 
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EQU 



<naine> 



EQU 



<exp> 



EQU assigns the value of <exp> to <nan\e>. If <exp> 
is an external symbol, an error is generated. If 
<naine> already has a value, an error is generated. 
If you want to be able to redefine a <naine> in your 
program, use the equal sign (=) directive instead. 



In many cases, EQU is used as 
substitution, like a macro. 



a primitive text 



<exp> may be any one of the following: 
1. 



A symbol. <name> becomes an 
symbol in <exp> . Shown as 
symbol table. 



alias for the 
an Alias in the 



2. 



3. 



An instruction name. Shown as an Opcode in the 
symbol table. 



A valid expression. Shown as 
(label) in the symbol table. 



a Number or L 



Any other entry, including text, index 
references, segment prefix and operands. Shown 
as Text in the symbol table. 



Exarr 


pie 


: 




FOO 




EQU 


BAZ 


B 
P8 




EQU 
EQU 


[BP+8] 
DS: [BP+81 


CBD 




EQU 


AAD 


ALL 




EQU 


DEFREC<2,3 


BMP 
FPV 




EQU 
EQU 


6 
6.3E7 



must be defined in this 

module or an error 

results 

index reference (Text) 

segment prefix 

and operand (Text) 

an instruction name 

(Opcode) 

4> ;DEFREC = record name 

<2,3,4> = initial values 

for fields of record 

constant value 

floating point (text) 
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Equ al Sign 



<naine> 



<exp> 



<exp> must be a valid expression. It is shown as a 
Number or L (label) in the symbol table (same as 
<exp> type 3 under the EQU directive above) . 

The equal sign (=) allows the user to set and to 
redefine symbols. The equal sign is like the EQU 
directive, except the user can redefine the symbol 
without generating an error. Redefinition may take 
place more than once, and redefinition may refer to 
a previous definition. 



Example; 




FOO 


5 


FOO EQU 


6; 


FOO 


7 


FOO 


FOO+3 



; the same as FOO EQU 5 

;error, FOO cannot be 

; redefined by EQU 

;F00 can be redefined 

;only by another = 

; redefinition may refer 

;to a previous definition 
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EVEN 



EVEN 



The EVEN directive causes the program counter to go 
to an even boundary; that is, to an address that 
begins a word. I£ the program counter is not 
already at ah even boundary, EVEN causes the 
assembler to add a NOP instruction so that the 
counter will reach an even boundary. 



An error results if EVEN 
byte-aligned segment. 



is used with 



Example: 

Before: The PC points to 0019 hex (25 decimal) 

EVEN 

After: The PC points to lA hex (26 decimal) 
0019 hex now contains a NOP instruction 
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EXTRN 

EXTRN <name>:<type> [r . . .] 

<naine> is a symbol that is defined in another 
module. <name> must have been declared PUBLIC in 
the module where <name> is defined. 

<type> may be any one of the following, but must be 
a valid type for <name>: 

1. BYTE, WORD, or DWORD 

2. NEAR or FAR for labels or procedures (defined 
under a PROC directive) 

3. ABS for pure numbers (implicit size is WORD, 
but includes BYTE) 

Unlike the 8080 assembler, placement of the EXTRN 
directive is significant. If the directive is 
given with a segment, the assembler assumes that 
the symbol is located within that segment. If the 
segment is not known, place the directive outside 
all segments, then use either 

ASSUME <seg-reg>:SEG <name> 

or an explicit segment prefix. 



NOl'E 

If a mistake is made and the symbol is not 
in the segment, MS-LINK will take the 
offset relative to the given segment, if 
possible. If the real segment is less than 
64K bytes away from the reference, MS-LINK 
may find the definition. If the real 
segment is more than 64K bytes away, 
MS-LINK will fail to make the- link between 
the reference and the definition and will 
return an error message. 
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Example: 

In Same Segment: 

In Module 1: 



In Another Segment: 
In Module 1: 
CSEGA SEGMENT 



CSEG 



.SEGMENT 
PUBLIC TAGN 



PUBLIC TAGF 



TAGN: 



TAGF: 



CSEG 



ENDS 



CSEGA ENDS 



In Module 2: 



CSEG 



In Module 2: 



SEGMENT 

EXTRN TAGN: NEAR 



EXTRN TAGF: FAR 
CSEGB SEGMENT 



CSEG 



JMP TAGN 
ENDS 



JMP TAGF 



CSEGB 



ENDS 
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GROUP 



<narae> 



GROUP 



<seg-naine> I , . . .] 



The GROUP directive collects the segments named 
after GROUP (<seg-name>s) under one name. The 
GROUP is used by MS-LINK so that it knows which 
segments should be loaded together (the order the 
segments are named here does not influence the 
order in which the segments are loaded. The order 
in which the segments are loaded is determined by 
the CLASS designation of the SEGMENT directive, or 
by the order you name object modules in response to 
the MS-LINK Object Module: prompt). 

All segments in a GROUP must fit into 64K bytes of 
memory. The assembler does not check this at all, 
but leaves the checking to MS-LINK. 

<seg-name> may be one of the following: 

1 



A segment 
directive, 
reference. 



name, assigned by a SEGMENT 
The name may be a forward 



2. An expression: either SEG <var> 

or SEG <label> 
Both of these entries resolve themselves to a 
segment name (see SEG operator. Section 3.3). 

Once you have defined a group name, you can use the 
name: 



1. As an immediate value: 



MOV AX,DGROUP 
MOV DS,AX 

DGROUP is the paragraph address of the base of 
DGROUP. 

In ASSUME statements: 

ASSUME DS: DGROUP 

The DS register can now be used to reach any 
symbol in any segment of the group. 
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3. As an operand prefix (for segment override): 

MOV BX, OFFSET DGROUP:FOO 
DW DGROUP:FOO 
DD DGROUP : FOO 

DGROUP: forces the offset to be relative to 
DGROUP, instead of to the segment in which FOO 
is defined. 

Example (Using GROUP to combine segments) : 

In Module A: 

CGROUP GROUP XXX, YYY 
XXX SEGMENT 

ASSUME CS: CGROUP 



XXX ENDS 
YYY SEGMENT 



YYY ENDS 
END 

In Module B: 

CGROUP GROUP Z2Z 
ZZZ SEGMENT 

ASSUME CS: CGROUP 



ZZZ ENDS 
END 
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INCLUDE <filename> 



The INCLUDE directive inserts source code from an 
alternate assembly language source file into the 
current source file during assembly. Use of the 
INCLUDE directive eliminates the need to repeat an 
often-used sequence of statements in the current 
source file. 

The <filename> is any valid file specification for 
the operating system. If the device designation is 
other than the default, the source filename 
specification must include it. The default device 
designation is the currently logged drive or 
device. 

The included file is opened and assembled into the 
current source file immediately following the 
INCLUDE directive statement. When end-of-file is 
reached, assembly resumes with the next statement 
following the INCLUDE directive. 

Nested INCLUDES are allowed (the file inserted with 
an INCLUDE statement may contain an INCLUDE 
directive). However, this is not a recommended 
practice with small systems because of the amount 
of memory that may be required. 

The file specified must exist. If the file is not 
found, an error is displayed, and the assembly 
aborts. 

On a Macro Assembler listing, the letter C is 
printed between the assembled code and the source 
line on each line assembled from an included file. 
See Section 5.5, "Formats of Listings and Symbol 
Tables," for a description of listing file formats. 

Example: 

INCLUDE ENTRY 
INCLUDE B: RECORD. TST 



ACTION: INSTRUCTIONS AND DIRECTIVES 



Page 4-19 



LABEL 



<name> 



LABEL 



<type> 



By using LABEL to define a <name>, you cause the 
assembler to associate the current segment offset 
with <name>. 

The item is assigned a length of 1. 

<type> varies depending on the use of <name>. 
<name> may be used for code or for data. 

For code (for example, as a JMP or CALL operand): 

<type> may be either NEAR or FAR. <name> cannot be 
used in data manipulation instructions without 
using a type override. 

If you wish, you can define a NEAR label using the 
<name>: form (the LABEL directive is not used in 
this case). If you are defining a BYTE or WORD 
NEAR label, you can place the <name>: in front of 
a Define directive. 

When using a LABEL for code (NEAR or FAR) , the 
segment must be addressable through the CS 
register. 

Example - For Code: 



SUBRTF LABEL FAR 

SUBRT: (first instruction) 



; colon = NEAR label 



/ 
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2. For data: 

<type> may be BYTE, WORD, DWORD, <structure-name> , 
or <record-name>. When STRUC or RECORD name is 
used, <name> is assigned the size of the structure 
or record. 

Example - For Data: 

BARRAY LABEL BYTE 
ARRAY DW LOO DUP(O) 



ADD AL, BARRAY [99] jADD 100th byte to AL 
ADD AX, ARRAY [981 ;ADD 50th word to AX 

By defining the array two ways, you can access 
entries either by byte or by word. Also, you can 
use this method for STRUC. It allows you to place 
your data in memory as a table, and to access it 
without the offset of the STRUC. 

Defining the array two ways also permits you to 
avoid using the PTR operator. The double defining 
method is especially effective if you access the 
data different ways. It is easier to give the 
array a second name than to remember to use PTR. 



ACTION: INSTRUCTIONS AND DIRECTIVES 



Page 4-21 



NAM E 
NAME 



<module-narae> 

<moclule-nanie> must not be a reserved word. The 
module name may be any length, but Macro Assembler 
uses only the first six characters and truncates 
the rest. 

The module name is passed to MS-LINK, but otherwise 
has no significance for the assembler. Macro 
Assembler does check to see if more than one module 
name has been declared. 



Every module has a name, 
the module name from: 



Macro Assembler derives 



1. A valid NAME directive statement 

2. If the module does not contain a NAME 
statement. Macro Assembler uses the first six 
characters of a TITLE directive statement. The 
first six characters must be legal as a name. 



Example: 
NAME CURSOR 
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ORG 

ORG <exp> 

The location counter is set to the value of <exp>, 
and the assembler assigns generated code starting 
with that value. 

All names used in <exp> must be known on pass 1. 

The value of <exp> must either evaluate to an 

absolute or must be in the same segment as the 
location counter. 

Example: 

ORG 120H ;2-byte absolute value 

; maximum=OFFFFH 
ORG $+2 ;skip two bytes 

Example - ORG to a boundary (conditional) : 

CSEG SEGMENT PAGE 
BEGIN = $ 



IF ($-BEGIN) MOD 256 ; if not already on 

; 256-byte boundary 
ORG {$-BEGIN)+256-({$-BEGIN) MOD 256) 
ENDIF 

See Section 4.2.2, "Conditional Directives," for an 
explanation of conditional assembly. 
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PROC 



<procname> PROC [NEAR] 

or [FAR] 



RET 
<procname> ENDP 



The default, if no operand is specified, is NEAR. 
Use FAR if: 



1. The procedure name is an operating system entry 
point 

2. The procedure will be called from code which 
has another ASSUME CS value 

Each PROC block should contain a RET statement. 

The PROC directive serves as a structuring device 
to make your programs more understandable. 

The PROC directive, through the NEAR/FAR option, 
informs CALLs to the procedure to generate a NEAR 
or a FAR CALL, and RETs to generate a NEAR or a FAR 
RET. PROC is used, therefore, for coding 
simplification so that the user does not have to 
worry about NEAR or FAR for CALLs and RETs. 

A NEAR CALL or RETURN changes the IP but not the CS 
register. A FAR CALL or RETURN changes both the IP 
and the CS registers. 

Procedures are executed either in line, from a JMP, 
or from a CALL. 

PROCs may be nested, which means that they are put 
in line. 

Combining the PUBLIC directive with a PROC 
statement (both NEAR and FAR) , permits you to make 
external CALLs to the procedure or to make other 
external references to the procedure. 
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Example: 

PUBLIC FAR_NAME 
FAR_NAME PROC FAR 

CALL NEAR_NAME 

RET 
FAR_NAME ENDP 

PUBLIC NEAR_NAME 
NEAR NAME PROC NEAR 



RET 
NEAR NAME 



ENDP 



The second subroutine above can be called directly 
from a NEAR segment (that is, a segment addressable 
through the same CS and within 64K) : 

CALL NEAR NAME 



A FAR segment (that is, any other segment that is 
not a NEAR segment) must call to the first 
subroutine, which then calls the second (an 
indirect call) : 

CALL FAR NAME 
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PUBLIC 



PUBLIC 



<symbol> [,...] 



Place a PUBLIC directive statement in any module 
that contains symbols you want to use in other 
modules without defining the symbol again. PUBLIC 
makes the listed symbol (s), which are defined in 
the module where the PUBLIC statement appears, 
available for use by other modules to be linked 
with the module that defines the symbol (s) . This 
information is passed to MS-LINK. 



<symbol> may be a number, a variable, 
(including PROC labels). 



label 



<symbol> may not be a register name or a symbol 
defined (with EQU) by floating point numbers or by 
integers larger than two bytes. 



Example; 








PUBLIC 


GETINFO 


GETINFO 


PROC 


FAR 




PUSH 


BP 




MOV 


BP,SP 




POP 


BP 




RET 




GETINFO 


ENDP 





;save caller's register 
;get address parameters 
;body of subroutine 
; restore caller's reg 
; return to caller 



Example - illegal PUBLIC; 



PUBLIC PIE_BALD,HIGH_VALUE 
PIE_BALD EQU 3.1416 
HIGH VALUE EQU 999999999 
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.RADIX <exp> 

The default input base (or radix) for all constants 
is decimal. The .RADIX directive permits you to 
change the input radix to any base in the range 2 
to 16. 

<exp> is always in decimal radix, regardless of the 
current input radix. 

Example: 

MOV BX,OFFH 
.RADIX 16 
MOV BX,OFF 

The two MOVs in this example are identical. 

The .RADIX directive does not affect the generated 
code values placed in the .OBJ, .LST, or .CRF 
output files. 

The .RADIX directive does not affect the DD, DQ, or 
DT directives. Numeric values entered in the 
expression of these directives are always evaluated 
as decimal unless a data type suffix is appended to 
the value. 



Example: 



NUM_HAND 
HOT_HAND 
COOL HAND 



RADIX 16 
DT 
DQ 
DD 



773 J 773 = decimal 

773Q J 773 = octal here only 

773H ;now 773 = hexadecimal 
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RECORD 

<recordname> RECORD <f ieldnamo : <width> [=<exp>] , ( . . . ] 

<fieldname> is the name of the field. <width> 
specifies the number of bits in the field defined 
by <fieldname>. <exp> contains the initial (or 
default) value for the field. Forward references 
are not allowed in a RECORD statement. 

<fieldname> becomes a value that can be used in 
expressions. When you use <fieldname> in an 
expression, its value is the shift count to move 
the field to the far right. Using the MASK 
operator with the <fieldname> returns a bit mask 
for that field. 

<width> is a constant in the range 1 to 16 that 
specifies the number of bits contained in the field 
defined by <fieldname>. The WIDTH operator returns 
this value. If the total width of all declared 
fields is larger than 8 bits, then the assembler 
uses two bytes. Otherwise, only one byte is used. 

The first field you declare goes into the most 
significant bits of the record. Successively 
declared fields are placed in the succeeding bits 
to the right. If the fields you declare do not 
total exactly 8 bits or exactly 16 bits, the entire 
record is shifted right so that the last bit of the 
last field is the lowest bit of the record. Unused 
bits will be in the high end of the record. 

Example: 

FOO RECORD HIGH: 4 , MID: 3 , LOW: 3 

Initially, the bit map would be: 



<HIGH-> <MID> <LOW> 



Total bits >8 means use a word; but total bits <16 
means right shift, place undeclared bits at high 
end of word. Thus: 
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0000001111000000 4— MASK 



1 1 1 1 1 


1 1 1 


1 


1 1 


not 


<HIGH-> 


<MID> 


<LOW> 


declared 


WIDTH 


Shift 


count 



<exp> contains the initial value for the field. If 
the field is at least 7 bits wide, you can use an 
ASCII character as the <exp>. 

Example: 

HIGH:7»'Q' 



To initialize records, use the same method used for 
DB. The format is: 

t<name>] <recordname> < [exp] [»...] > 

or 

(<name>] <recordname> l<exp> DUP(< [exp][ , . . ,] >) 

The name is optional. When given, name is a label 
for the first byte or word of the record storage 
area. 



The recordname is the name used as a label for 
RECORD directive. 



the 



The [exp] (both forms) contains the values you want 
placed into the fields of the record. In the 
latter case, the parentheses and angle brackets are 
required only around the second [exp] (following 
DUP) . If lexpl is left blank, either the default 
value applies (the value given in the original 
record definition) , or the value is indeterminate 
(when not initialized in the original record 
definition). For fields that are already 
initialized to values you want, place consecutive 
commas to skip over (use the default values of) 
those fields. 

For example : 

FOO <,,?> 



From the previous example, the 7 would be placed 
into the LOW field of the record FOO. The fields 
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HIGH and MID would be left as declared (in this 
case, uninitialized). 

Records may be used in expressions (as an operand) 
in the form: 

recordname< [value ( ,...]] > 

The value entry is optional. The angle brackets 
must be coded as shown , even if the optional values 
are not given. A value entry is the value to be 
placed into a field of the record. For fields that 
are already initialized to values you want, place 
consecutive commas to skip over (use the default 
values of) those fields, as shown above. 

Example: 



FOO 



RECORD HIGH:5,MID:3,LOW:3 



BAX FOO <> ; leave undeterminate here 
JANE FOO 10 DUP(<16,8>) ;HIGH-16 rMID-S , 
;LOW=? 



MOV DXrOFFSET JANE [2] 

;get beginning record address 
AND DX,MASK MID 
MOV CL,MID 
SHR DX,CL 
MOV CL»WIDTH MID 
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SE GMENT 

<segname> SEGMENT (<align>1 [<combine>l (<'class'>l 

<segname> ENDS 

At runtime, all instructions that generate code and 
data are in (separate) segments. Your program may 
be a segment f part of a segment, several segments, 
parts of several segments, or a combination of 
these. If a program has no SEGMENT statement, an 
MS-LINK error (invalid object) will result at link 
time. 

The <segment naroe> must be a unique, legal name. 
The segment name must not be a reserved word. 

<align> may be PARA (paragraph - default) , BYTE, 
WORD, or PAGE. 

<corabine> may be PUBLIC, COMMON, AT <exp>, STACK, 
MEMORY, or no entry (which defaults to not 
combinable, called Private in the Microsoft LINK 
section of the Ma cro Assemb ler Manual ) . 

<class> name is used to group segments at link 
time. 

All three operands are passed to MS-LINK. 

The alignm ent type tells the Linker on what kind of 
boundary you want the segment to begin. The first 
address of the segment will be, for each alignment 
type: 

PAGE - address is xxxOOH (low byte is 0) 
PARA - address is xxxxOH (low nibble is 0) 

bit map - |x|x|x|x|0|0|0|0| 
WORD - address is xxxxeH (e=even number; low bit 

is 0) 

bit map - |x|x|x|x| x|x{x|0 | 
BYTE - address is xxxxxH (place anywhere) 
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The combin e type tells MS-LINK how to arrange the 
segments of a particular class name. The segments 
are mapped as follows for each combine type: 



None (not 



A A 



combinable or Private) 

Q Private segments are loaded separately 
and remain separate. They may be 
physically contiguous but not logically, 
even if the segments have the same name. 

Each private segment has its own base 
address. 



Public 

m 

B 

Common 



-A- 



and Stack public segments of the same name and 
class name are loaded contiguously. 

Offset is from beginning of first segment 
loaded through last segment loaded. 
There is only one base address for all 
public segments of the same name and 
class name. (Combine type stack is 
treated the same as public. However, the 
Stack Pointer is set to the first address 
of the first stack segment. MS-LINK 
requires at least one stack segment.) 



Q Common segments of the same name and 
class name are loaded overlapping one 
another. There is only one base address 
for all common segments of the same name. 
The length of the common area is the 
length of the longest segment. 



A' I 
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Memory 

The memory combine type causes the segment (s) to be 
placed as the highest segments in memory. The 
first memory combinable segment encounter is placed 
as the highest segment in memory. Subsequent 
segments are treated the same as Common segments. 



NOTE 

This feature is not supported by MS-LINK. 
MS-LINK treats Memory segments the same as 
Public segments. 



AT <exp> 

The segment is placed at the PARAGRAPH address 
specified in <exp> . The expression may not be a 
forward reference. Also, the AT type may not be 
used to force loading at fixed addresses. Rather, 
the AT combine type permits labels and variables to 
be defined at fixed offsets within fixed areas of 
storage, such as ROM or the vector space in low 
memory. 



NOTE 

This restriction is imposed by MS-LINK and 
MS-DOS. 



Class names must be enclosed in quotation marks. 

Class names may be any legal name. Refer to 

Chapter 9 in the M S-DOS User' s Gu ide for more 
discussion. 



Segment definitions may be nested. When segments 
are nested, the assembler acts as if they are not 
and handles them sequentially by appending the 
second part of the split segment to the first. At 
ENDS for the split segment, the assembler takes up 
the nested segment as the next segment, completes 
it, and goes on to subsequent segments. 
Overlapping segments are not permitted. 
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For example: 

A SEGMENT 

B SEGMENT 
B ENDS 



A SEGMENT 



A ENDS 

B SEGMENT 



ENDS 
SEGMENT 



A ENDS 

A ENDS 

The following arrangement is not allowed: 
A SEGMENT 



B 



SEGMENT 



ENDS ;This is illegall 



ENDS 



Example : 



In module A: 

SEGA SEGMENT PUBLIC 'CODE* 
ASSUME CS:SEGA 



SEGA ENDS 
END 

In module B: 

SEGA SEGMENT PUBLIC 'CODE' 
ASSUME CS:SEGA 

;MS-LINK adds this segment to same 
; named segment in module A (and 
/others) i£ class name is the same. 
SEGA ENDS 
END 
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STRUG 

<structurename> STRUC 

<structurename> ENDS 

The STRUC directive is very much like RECORD, 
except STRUC has a multiple byte capability. The 
allocation and initialization of a STRUC block are 
the same as for RECORDS. 

Inside the STRUC/ENDS block, the Define directives 
(DB, DW, DD, DQ, DT) may be used to allocate space. 
The Define directives and Comments set off by 
semicolons (;) are the only statement entries 
allowed inside a STRUC block. 

Any label on a Define directive inside a STRUC/ENDS 
block becomes a <fieldname> of the structure. 
(This is how structure fieldnames are defined.) 
Initial values given to fieldnames in the 
STRUC/ENDS block are default values for the various 
fields. These field values are of two types: 
overridable or not overridable. A simple field, a 
field with only one entry (but not a DUP 
expression), is overridable. A multiple field, a 
field with more than one entry, is not overridable. 
For example: 



FOO DB 


1,2 


; is 


not 


overridable 








BAZ DB 


10 DUP{?) 


;is 


not 


overridable 








ZOO DB 


5 


;is 


overridable 



If the <exp> following the Define directive 

contains a string, it may be overridden by another 

string. However, if the overriding string is 
shorter than the initial string, the assembler will 

pad with spaces. If the overriding string is 

longer, the assembler will truncate the extra 
characters. 



ACTION: INSTRUCTIONS AND DIRECTIVES 



Page 4-35 



Usually, structure fields are used as operands in 
some expression. The format for a reference to a 
structure field is: 

<variable>.<field> 

<variable> represents an anonymous variable, 
usually set up when the structure is allocated. To 
allocate a structure, use the structure name as a 
directive with a label (the anonymous variable of a 
structure reference) and any override values in 
angle brackets: 



FOO 



STRUCTURE 



FOO 
GOO 



ENDS 
FOO 



<,7,,'J0E'> 



.<field> represents a label given to a DEFINE 
directive inside a STRUC/ENDS block (the period 
must be coded as shown) . The value of <f ield> will 
be the offset within the addressed structure. 

Example: 

To define a structure: 



S STRUC 






PIELDl 


DB 


lr2 


;not overridable 


FIELD2 


DB 


10 DUP(?) 


;not overridable 


PIELD3 


DB 


5 


;overridable 


FIELD4 


DB 


•DOBOSKY' 


;overridable 


S 


ENDS 







The Define directives in this example define the 
fields of the structure, and the order corresponds 
to the order values are given in the initialization 
list when the structure is allocated. Every Define 
directive statement line inside a STRUC block 
defines a field, whether or not the field is named. 



To allocate the structure: 

DBAREA S <,,7,'ANDY'> 
4 th 



;overrides 3rd and 
; fields only 
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To refer to a structure: 



MOV AL,[BX1 .FIELD3 
MOV AL,DBAREA.FIELD3 
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4.2.2 Conditional Directives 

Conditional directives allow users to design blocks of code 
which test for specific conditions. 

All conditionals follow the format: 
IFxxxx [argument] 

[ELSE 



. 1 
ENDIF 



Each IFxxxx must have a matching ENDIF to terminate the 
conditional. Otherwise, an 'Unterminated conditional' 
message is generated at the end of each pass. An ENDIF 
without a matching IF causes a Code 8, "Not in conditional 
block" error. 

Each conditional block may include the optional ELSE 
directive, which allows alternate code to be generated when 
the opposite condition exists. Only one ELSE is permitted 
for a given IF. An ELSE is always bound to the most recent, 
open IF. A conditional with more than one ELSE or an ELSE 
without a conditional will cause a Code 7, "Already had ELSE 
clause" error. 

Conditionals may be nested up to 255 levels. Any argument 
to a conditional must be known on pass 1 to avoid Phase 
errors and incorrect evaluation. For IF and IFE the 
expression must involve values which were previously 
defined, and the expression must be absolute. If the name 
is defined after an IFDEF or IFNDEF, pass 1 considers the 
name to be undefined, but it will be defined on pass 2. 

The assembler evaluates the conditional statement to TRUE 
(which equals any non-zero value) , or to FALSE (which equals 
OOOOH) . If the evaluation matches the condition defined in 
the conditional statement, the assembler either assembles 
the whole conditional block or, if the conditional block 
contains the optional ELSE directive, assembles from IF to 
ELSE; the ELSE to ENDIF portion of the block is ignored. 
If the evaluation does not match, the assembler either 
ignores the conditional block completely or, if the 
conditional block contains the optional ELSE directive, 
assembles only the ELSE to ENDIF portion; the IF to ELSE 
portion is ignored. 
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The following is a list of Macro Assembler conditional 
directives: IF <exp> 

If <exp> evaluates to nonzero, the statements 
within the conditional block are assembled. 



IFE <exp> 



If <exp> evaluates to 0, the statements in the 
conditional block are assembled. 



IFl Pass 1 Conditional 

If the assembler is in pass 1, the statements in 
the conditional block are assembled. IFl takes no 
expression. 

IF2 Pass 2 Conditional 

If the assembler is in pass 2, the statements in 
the conditional block are assembled. IF2 takes no 
expression. 



IFDEF <symbol> 



If the <symbol> is defined or has been declared 
External, the statements in the conditional block 
are assembled. 



IFNDEF <symbol> 



If the <symbol> is not defined or not declared 
External, the statements in the conditional block 
are assembled. 
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IFB <arg> 

The angle brackets around <arg> are required. 

If the <arg> is blank (none given) or null (two 
angle brackets with nothing in between, <>) » the 
statements in the conditional block are assembled. 

IFB (and IFNB) are normally used inside macro 
blocks. The expression following the IFB directive 
is typically a dummy symbol. When the macro is 
called, the dummy will be replaced by a parameter 
passed by the macro call. If the macro call does 
not specify a parameter to replace the dummy 
following IFB, the expression is blank, and the 
block will be assembled. (IFNB is the opposite 
case.) Refer to Section 4.2.3, "Macro Directives," 
for a full explanation. 

IFNB <'arq> 

The angle brackets around <arg> are required. 

IE <arq> is not blank, the statements in the 
conditional block are assembled. 

IFNB (and IFB) are normally used inside macro 
blocks. The expression following the IFNB 
directive is typically a dummy symbol. When the 
macro is called, the dummy will be replaced by a 
parameter passed by the macro call. If the macro 
call specifies a parameter to replace the dummy 
following IFNB, the expression is not blank, and 
the block will be assembled. (IFB is the opposite 
case.) Refer to Section 4.2.3, "Macro Directives," 
for a full explanation. 
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IFIDN <argl>,<arg2> 

The angle brackets around <argl> and <arg2> are 
required. 

If the string <argl> is identical to the string 
<arg2>, the statements in the conditional block are 
assembled. 

IFIDN (and IFDIF) are normally used inside macro 
blocks. The expression following the IFIDN 
directive is typically two dummy symbols. When the 
macro is called, the dumroys will be replaced by 
parameters passed by the macro call. If the macro 
call specifies two identical parameters to replace 
the dummys, the block will be assembled. (IFDIF is 
the opposite case.) Refer to Section 4.2.3, "Macro 
Directives," for a full explanation. 

IFDIF <argl>,<arg2> 

The angle brackets around <argl> and <arg2> are 
required. 

If the string <argl> is different from the string 
<arg2>, the statements in the conditional block are 
assembled. 

IFDIF (and IFIDN) are normally used inside macro 
blocks. The expression following the IFDIF 
directive is typically two dummy symbols. When the 
macro is called, the dummys will be replaced by 
parameters passed by the macro call. If the macro 
call specifies two different parameters to replace 
the dummys, the block will be assembled, (IFIDN is 
the opposite case.) 



ELSE 



END IF 



The ELSE directive allows you to generate alternate 
code when the opposite condition exists. ELSE may 
be used with any of the conditional directives. 
Only one ELSE is allowed for each IFxxxx 
conditional directive. ELSE takes no expression. 



This directive terminates a conditional block. An 
ENDIF directive must be given for every IFxxxx 
directive used. ENDIF takes no expression. ENDIF 
closes the most recent, unterminated IF. 
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4.2.3 Macro Directives 

The macro directives allow you to write blocks of code which 
can be repeated without r.ecoding. The blocks of code begin 
with either the macro definition directive or one of the 
repetition directives, and end with the ENDM directive. All 
of the macro directives may be used inside a macro block. 
In fact, nesting of macros is limited only by memory. 

The macro directives of the Macro Assembler include: 

macro definition: 
MACRO 

termination: 
ENDM 
EXITM 

unique symbols within macro blocks: 
LOCAL 

undefine a macro: 
PURGE 

repetitions: 

REPT (repeat) 

IRP (indefinite repeat) 

IRPC (indefinite repeat character) 

The macro directives also include some special macro 
operators: 

& (ampersand) 

; ? (double semicolon) 

! (exclamation mark) 

% (percent sign) 
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Macro Definition 

<name> MACRO [< dummy >,.. .] 

ENDM 

The block of statements from the MACRO statement 
line to the ENDM statement line comprises the body 
of the macro, or the macro's definition. 

<name> is like a label and conforms to the rules 
for forming symbols. After the macro has been 
defined, <name> is used to invoke the macro. 

A <dummy> is formed as any other name is formed. A 
<dummy> is a place holder that is replaced by a 
parameter in a one-for-one text substitution when 
the macro block is used. You should include all 
<duramy>s used inside the macro block on this line. 
The number of <dumroy>s is limited only by the 
length of a line. If you specify more than one 
<dummy>, they must be separated by commas. Macro 
Assembler interprets a series of <dummy>s the same 
as any list of symbol names. 



NOTE 

A <dummy> is always recognized exclusively 
as a dummy. Even if a register name (such 
as AX or BH) is used as a <dummy>, it will 
be replaced by a parameter during 
expansion. 



One alternative is to list no <dummy>s: 

<name> MACRO 

This type of macro block allows you to call the 
block repeatedly, even if you do not want or heed 
to pass parameters to the block. In this case, the 
block will not contain any <dummy>s. 

A macro block is not assembled when it is 
encountered. Rather, when you call a macro, the 
assembler "expands" the macro call statement by 
bringing in and assembling the appropriate macro 
block. 

MACRO is an extremely powerful directive. With it, 
you can change the value and effect of any 
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instruction mnemonic, directiver label, variable, 
or symbol. When Macro Assembler evaluates a 
statement, it first looks at the macro table It 
builds during pass 1. If it sees a name there that 
matches an entry in a statement, it acts 
accordingly. (Remember: Macro Assembler evaluates 
macros, then instruction mnemonics/directives.) 

If you want to use the TITLE, SUBTTL, or NAME 
directives for the portion of your program where a 
macro block appears, you should be careful about 
the form of the statement. If, for example, you 
enter SUBTTL MACRO DEFINITIONS, Macro Assembler 
will assemble the statement as a macro definition 
with SUBTTL as the macro name and DEFINITIONS as 
the dummy. To avoid this problem, alter the word 
MACRO in some way; e.g., - MACRO, MACROS, and so 
on. 



ACTION: INSTRUCTIONS AND DIRECTIVES 



Page 4-44 



Calling a Macro 



To use a macro, enter a macro call statement: 

<name> t<pararoeter>, . . .1 

<name> is the <name> of the macro block. A 
<pararaeter> replaces a <dummy> on a one-for-one 
basis. The number of parameters is limited only by 
the length of a line. If you enter more than one 
parameter, they must be separated by commas, 
spaces, or tabs. If you place angle brackets 
around parameters separated by commas, the 
assembler will pass all the items inside the angle 
brackets as a single parameter. For example: 

FOO 1,2,3,4,5 
passes five parameters to the macro, but 

FOO <1,2,3,4,5> 

passes only one. 

The number of parameters in the macro call 
statement need not be the same as the number of 
<dummy>s in the MACRO definition. If there are 
more parameters than <dummy>s, the extras are 
ignored. If there are fewer, the extra <dummy>s 
will be made null. The assembled code will include 
the macro block after each macro call statement. 



'( 



Example : 
GEN 



MACRO 

MOV 

ADD 

MOV 

ENDM 



XX,YY,ZZ 
AX, XX 
AX,YY 
ZZ,AX 



If you then enter a macro call statement: 

GEN DUCK, DON, FOO 
the assembler generates the statements: 



MOV 
ADD 
MOV 



AX, DUCK 
AX, DON 
FOO, AX 



On your program listing, these statements will be 
preceded by a plus sign (+) to indicate that they 
came from a macro block. 
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End Macro 

ENDM 

ENDM tells the assembler that the MACRO or Repeat 
block is ended. 

Every MACRO, REPT, IRP, and IRPC must be terminated 
with the ENDM directive. Otherwise, the 
"Unterminated REPT/IRP/IRPC/MACRO" message is 
generated at the end of each pass. An unmatched 
ENDM also causes an error. 

If you wish to be able to exit from a MACRO or 
repeat block before expansion is completed, use 
EXITM. 
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Exit Macro 



EXITM 



The EXITM directive is used inside a MACRO or 
Repeat block to terminate an expansion when some 
condition makes the remaining expansion unnecessary 
or undesirable. Usually EXITM is used in 
conjunction with a conditional directive. 

When an EXITM is assembled, the expansion is exited 
immediately. Any remaining expansion or repetition 
is not generated. If the block containing the 
EXITM is nested within another block, the outer 
level continues to be expanded. 



Example: 

FOO MACRO 



= 





REPT 


X 


ss 


X+1 


IFE 


X-OFFH ;test X 


EXITM 


;if true, exit REPT 


ENDIF 




DB 


X 


ENDM 




ENDM 
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LOCAL 

LOCAL <dummy> [ ,<dununy> . . .) 

The LOCAL directive is allowed only inside a macro 
definition block. A LOCAL statement must precede 
all other types of statements in the macro 
definition. 

When LOCAL is executed, the assembler creates a 
unique symbol for each <dummy> and substitutes that 
symbol for each occurrence of the <dummy> in the 
expansion. These unique symbols are usually used 
to define a label within a macro, thus eliminating 
multiple-defined labels on successive expansions of 
the macro. The symbols created by the assembler 
range from ??0000 to ??FFFF. Users should avoid 
the form ??nnnn for their own symbols. 



Example: 



0000 






FUN 


SEGMENT 








ASSUME 


CS:FUN,DS:FUN 








FOO MACRO 


NUM,Y 








LOCAL 


A,B,C,D,E 








A: DB 


7 








B: DB 


.8 








C: DB 


Y 








D: DW 


Y+1 








E: DW 


NUM+1 








JMP 


A 








ENDM 










FOO 


0C00H,0BEH 


0000 


07 


+ 


770000 




DB 7 


0001 


08 


+ 


770001 




DB 8 


0002 


BE 


+ 


770002 




DB OBEH 


0003 


OOBF 


+ 


770003 




DW OBEH+1 


0005 


OCOl 


+ 


770004 




DW OCOOH+1 


0007 


EB F7 


+ 


I 


TMP 
'00 


770000 
03C0H,0FFH 


0009 


07 


+ 


770005 




DB 7 


OOOA 


08 


+ 


770006 




DB 8 


OOOB 


FF 


+ 


770007 




DB OFFH 


OOOC 


0100 


+ 


770008 




DW OFFH+1 


OOOE 


03C1 


+ 


770009 




DW 03C0H+1 


0010 


EB F7 


+ 




IMP 


770005 


0012 






FUN I 
I 


SNDS 

:nd 





Notice that Macro Assembler has substituted LABEL 
names in the form 7?nnnn for the instances of the 
dummy symbols. 
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PURGE 

PURGE <macro-name> [,...] 

PURGE deletes the definition of the macro (s) listed 
after it. 

PURGE provides three benefits: 

1. It frees text space of the macro body. 

2. It returns any instruction mnemonics or 
directives that were redefined by macros to 
their original function. 

3. It allows you to "edit out" macros from a macro 
library file. You may find it useful to create 
a file that contains only macro definitions. 
This method allows you to use macros repeatedly 
with easy access to their definitions. 
Typically, you would then place an INCLUDE 
statement in your program file. Following the 
INCLUDE statement, you could place a PURGE 
statement to delete any macros you will not use 
in this program. 

It is not necessary to PURGE a macro before 

redefining it. Simply place another MACRO 

statement in your program, reusing the macro 
name. 

Example: 

INCLUDE MACRO. LIB 
PURGE MACl 

MACl ; tries to invoke purged macro 

; returns a syntax error 
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Repeat Directives 

The directives in this group allow the operations in a block 
of code to be repeated £or the number o£ times you specify. 
The major differences between the Repeat directives and 
MACRO directive are: 

1. MACRO gives the block a name by which to call in 
the code wherever and whenever needed; the macro 
block can be used in many different programs by 
simply entering a macro call statement. 

2. MACRO allows parameters to be passed to the macro 
block when a MACRO is called; hence, parameters 
can be changed. 

Repeat directive parameters must be assigned as a part of 
the code block. If the parameters are known in advance and 
will not change, and if the repetition is to be performed 
for every program execution, then Repeat directives are 
convenient. With the MACRO directive, you must call in the 
MACRO each time it is needed. 

Note that each Repeat directive must be matched with the 
ENDM directive to terminate the repeat block. 
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Repeat 
REPT <exp> 
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ENDM 



Repeat, block of statements between REFT and ENDM 

<exp> times. <exp> is evaluated as a 16-bit 

unsigned number. If <exp> contains an External 

symbol or undefined operands, an error is 
generated. 



Example: 

10 

assembles as: 
0000 

10 



0000' 


01 


0001' 


02 


0002' 


03 


0003' 


04 


0004' 


05 


0005' 


06 


0006' 


07 


0007' 


08 


0008' 


09 


0009' 


OA 



- 







REPT 


10 


;generates 
;DB 1 - DB 


s 


X+1 




DB 


X 




ENDM 






_ 







REPT 


10 


;generates 
;DB 1 - DB 


= 


X+1 




DB 


X 




ENDM 






DB 


X 




DB 


X 




DB 


X 




DB 


X 




DB 


X 




DB 


X 




DB 


X 




DB 


X 




DB 


X 




DB 


X 




END 
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ENDM 



Parameters must be enclosed in angle brackets . 
Parameters may be any legal symbol r string, 
numeric, or character constant. The block of 
statements is ' repeated for each parameter. Each 
repetition substitutes the next parameter for every 
occurrence of <dummy> in the block. If a parameter 
is null (i.e.»<>)# the block is processed once 
with a null parameter. 



Example: 

IRP X,<l,2r3,4,5,6,7,8,9,10> 

DB X 

ENDM 

This example generates the same bytes (DB 1 to DB 
10) as the REPT example. 

When IRP is used inside a MACRO definition block, 
angle brackets around parameters in the macro call 
statement are removed before the parameters are 
passed to the macro block. An example, which 
generates the same code as above, illustrates the 
removal of one level of brackets from the 
parameters: 

FOO MACRO X 

IRP y,<x> 

DB Y 

ENDM 

ENDM 

When the macro call statement 

FOO <1,2,3,4,5,6,7,8,9,10> 

is assembled, the macro expansion becomes: 

IRP Y,<1,2,3,4,5,6,7,8,9,10> 

DB Y 

ENDM 

The angle brackets around the parameters will be 
removed, and all items are passed as a single 
parameter . 
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Indefinite Repeat Character 
IRPC <duininy>,<8tring> 



ENDM 



The statements in the block are repeated once for 
each character in the string. Bach repetition 
substitutes the next character in the string for 
every occurrence jf <duiiuny> in the block. 



Example: 

IRPC X, 0123456789 

DB X+l 

ENDM 

This example generates the same code (DB 1 to DB 
10) as the two previous examples. ' 
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Special Macro Operators 

Several special operators can be used in a 
select additional assembly functions. 



macro block to 



Ampersand concatenates text or symbols. (The 
ampersand may not be used in a macro call 
statement.) A dummy parameter in a quoted string 
will not be substituted in expansion unless 
preceded immediately by an ampersand. To form a 
symbol from text and a dummy, put an ampersand 
between them. 

For example: 

ERRGEN MACRO X 

ERROR&X: PUSH BX 

MOV BX,'&X' 

JMP ERROR 

ENDM 



The call ERRGEN A will then generate: 



ERRORA: PUSH 
MOV 
JMP 



B 

BX , • A • 

ERROR 



In Macro Assembler, the ampersand will not appear 
in the expansion. One ampersand is removed each 
time a dummys or Gtdummy is found. For complex 
macros, where nesting is involved, extra ampersands 
may be needed. You need to supply as many 
ampersands as there are levels of nesting. 
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For 


example: 














Corr 


ect 


f^qrni 






Incorrect 


fo 


rm 


FOO 
X&&Z 




MACRO 

IRP 

DB 

ENDM 

ENDM 


X 

z, 
z 


<1,2,3> 


FOO 

x&z 


MACRO 

IRP 

DB 

ENDM 

ENDM 




X 

Z,<1,2,3> 
Z 



When called, for example, by FOO BAZ , the expansion 
would be (correctly in the left column, incorrectly 
in the right) : 

1. MACRO build, find <dummy>s and change to dl 

IRP Z,<1,2,3> IRP Z,<1,2,3> 
dlSZ DB Z dlZ DB Z 

ENDM ENDM 

2. MACRO expansion, substitute parameter text for 
dl 



IRP 
BAZ&Z DB 

ENDM 



Z,<1,2,3> IRP 
ZBAZZ DB Z 
ENDM 



Z,<1,2,3> 



3. IRP build, find dummys and change to dl 
BAZ&dl DB dl BAZZ DB dl 

4. IRP expansion, substitute parameter text for dl 



BAZl 


DB 


1 


BAZZ 


DB 


1 


BAZ 2 


DB 


2 


BAZZ 


DB 


2<— 1 


BAZ 3 


DB 


3 


BAZZ 


DB 


3 



|_|;here it's an error, 
I ;multi-def ined symbol 
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<text> Angle brackets cause Macro Assembler to treat the 
text between the angle brackets as a single 
literal. Placing parameters to a macro call inside 
angle brackets; or placing the list of parameters 
following the IRP directive inside angle brackets 
causes two results: 

1. All text within the angle brackets is seen as a 
single parameter, even if commas are used. 

2. Characters that have special functions are 
taken as literal characters. For example, the 
semicolon inside angle brackets <;> becomes a 
character, not the indicator that a comment 
follows. 

One set of angle brackets is removed each time the 
parameter is used in a macro. When using nested 
macros, you will need to supply as many sets of 
angle brackets around parameters as there are 
levels of nesting. 

; ; In a macro or repeat block, a comment preceded by 
two semicolons is not saved as a part of the 
expansion. 

The default listing condition for macros is .XALL 
(see Section 4.2.4, "Listing Directives," below). 
Under the influence of .XALL, comments in macro 
blocks are not listed because they do not generate 
code. 

If you decide to place the .LALL listing directive 
in your program, then comments inside macro and 
repeat blocks are saved and listed. This can be 
the cause of an "out of memory error." To avoid 
this error, place double semicolons before comments 
inside macro and repeat blocks, unless you 
specifically want a comment to be retained. 



An exclamation point may be entered in an argument 
to indicate that the next character is to be taken 
literally. Therefore, !; is equivalent to <;>. 
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% The percent sign is used only in a macro argumeht 
to convert the expression that follows it (usually 
a symbol) to a number in the current radix. During 
macro expansion, the number derived from converting 
the expression is substituted for the dummy. Using 
the % special operator allows a macro call by 
value. (Usually, a macro call is a call by 
reference, with the text of the macro argument 
substituting exactly for the dummy.) 

The expression following the % must evaluate to an 
absolute (non-relocatable) constant. 

Example: 

PRINTE MACRO MSG,N 

%OUT * MSG,N * 

ENDM 

SYMl EQU 100 

SYM2 EQU 200 

PRINTE <SYM1 + SyM2 = >,%(SYM1 + SYM2) 

Normally, the macro call statement would cause the 
string (SYMl + SYM2) to be substituted for the 
dummy N. The result would be: 

%OUT * SYMl + SYM2 = (SYMl + SYM2) * 

When the % is placed in front of the parameter , 
the assembler generates: 

%OUT * SYMl + SYM2 = 300 * 
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4.2.4 Listing Directives 

Listing directives perform two general functions: format 
control and listing control. Format control directives 
allow the programmer to insert page breaks and direct page 
headings. Listing directives turn on and off the listing of 
all or part of the assembled file. 



PAGE 

PAGE [<length>] I,<width>l 
PAGE [+] 

PAGE with no arguments or with the optional {,■¥] 
argument causes the assembler to start a new output 
page. The assembler puts a form feed character in 
the listing file at the end of the page. 

The PAGE directive with either the length or width 
arguments does not start a new listing page. 

The value of <length>r if included, becomes the new 
page length (measured in lines per page) and must 
' be in the range 10 to 255. The default page length 
is 50 lines per page. 

The value of <width>r if included, becomes the new 
page width (measured in characters) and must be in 
the range 60 'to 132. The default page width is 80 
characters. 

The plus sign {■*■) increments the major page number 
and resets the minor page number to one. Page 
numbers are in the form major-minor. The PAGE 
directive without the -f increments only the minor 
portion of the page number. 

Example: 



PAGE -f ;increnent major, set minor to 1 



PAGE 58,60 ;page length^SS lines, 
;width"60 characters 
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TITLE 

TITLE <text> 

TITLE specifies a title to be listed on the first 
line of each page. The <text> may be up to 60 
characters long. If more than one TITLE is given, 
an error results. The first six characters of the 
title, if legal, are used as the module name, 
unless a NAME directive is used. 

Example: 

TITLE PROGl — 1st Program 



If the NAME directive is not used, the module name 
is now PROGl — 1st Program. This title text will 
appear at the top of every page of the listing. 
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SUBTITL E 

SUBTTL <text> 

SUBTTL specifies a subtitle to be listed in each 
page heading on the line after the title. The 
<text> is truncated after 60 characters. 

Any number of SUBTTLs may be given in a program. 
Each time the assembler encounters SUBTTL, it 
replaces the <text> from the previous SUBTTL with 
the <text> from the most recently encountered 
SUBTTL. To turn off SUBTTL for part of the output, 
enter a SUBTTL with a null string for <text>. 

Example: 

SUBTTL SPECIAL I/O ROUTINE 

SUBTTL 



The first SUBTTL causes the subtitle SPECIAL I/O 
ROUTINE to be printed at the top of every page. 
The second SUBTTL turns off subtitle (the subtitle 
line on the listing is left blank) . 
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%OUT 



%OUT <text> 



The text is listed on the terminal during assembly. 

%OUT is useful for displaying progress through a 

long assembly or for displaying the value of 
conditional assembly switches. 

%OUT will output on both passes. If only one 
printout is desired, use the IFl or IF2 directive, 
depending on which pass you want displayed. See 
Section 4.2.2, "Conditional Directives," for 
descriptions of the IFl and IF2 directives. 

Example: 



%OUT *Assembly half done* 

The assembler will send this message to the 
terminal screen when encountered. 

IFl 

%OUT *Pass 1 started* 

ENDIF 

IF2 

%00T *Pass 2 started* 

ENDIF 
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.LIST 
.XLIST 



•LIST lists all lines with their code (the default 
condition) . 

.XLIST suppresses all listing. 

If you specify a listing file following the 
Listing: prompt, a listing file with all the 
source statements included will be printed. 

When .XLIST is encountered in the source file, 
source and object code will not be listed. .XLIST 
remains in effect until a .LIST is encountered. 

.XLIST overrides all other listing directives. 
Nothing will be listed, even if another listing 
directive (other than .LIST) is encountered. 

Example: 



■XLIST ;listing suspended here 
.LIST ;listing resumes here 
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.LFCOND 



.TFCOND 



•SECOND suppresses portions of the listing that 
contain conditional false expressions. 



.LECOND assures the listing of conditional 
expressions that evaluate false. This is the 
default condition. 



.TECOND toggles the current setting. .TFCOND 
operates independently from .LFCOND and .SECOND. 
.TFCOND toggles the default setting, which is set 
by the presence or absence of the /X switch when 
the assembler is running. When /X is used, .TFCOND 
will cause false conditionals to list. When /X is 
not used, .TFCOND will suppress false conditionals. 



.XALL 



.XALL is the default. 

.XALL lists source code and object code produced by 
a macro, but source lines which do not generate 
code are not listed. 



,LALL 



.LALL lists the complete macro text for all 
expansions, including lines that do not generate 
code. Comments preceded 
will not be listed. 



by two semicolons (;;) 



.SALL 



.SALL suppresses listing of 
code produced by macros. 



all text and object 
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.CREF 
.XCREF 

.CREF 

.XCREF (<variable list>l 



•CREF is the default condition. .CREF remains 
effect until Macro Assembler encounters .XCREF. 



in 



.XCREF without arguments turns off the .CREF 
(default) directive. .XCREF remains in effect 
until Macro Assembler encounters .CREF. Use .XCREF 
to suppress the creation of cross-references in 
selected portions of the file. Use .CREF to 
restart the creation of a cross-reference file 
after using the .XCREF directive. 

If you include one or more variables following 
.XCREF, these variables will not be placed in the 
listing or cross-reference file. All other 
cross-referencing, however, is not affected by an 
.XCREF directive with arguments. Separate the 
variables with commas. 

Neither .CREF nor .XCREF without arguments takes 
effect unless you specify a cross-reference file 
when running the assembler. .XCREF <variable list> 
suppresses the variables from the symbol table 
listing regardless of the creation of a 
cross-reference file. 

Example: 



.XCREF CURSOR,FOO,GOO,BAZ,ZOO 

; these variables will not be 

; in the listing or cross-reference file 
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CHAPTER 5 
ASSEMBLING A MACRO ASSQffiLER SOURCE FILE 



Assembling a program with Macro Assembler requires two types 
o£ commands: a command to start Macro Assembler, and 
answers to command prompts. In addition, four switches 
control alternate Macro Assembler features. Usually, you 
will type all the commands to Macro Assembler on the 
terminal keyboard. As an option, answers to the command 
prompts and any switches may be contained in response 
(batch) • file. Two command characters are provided to assist 
you while entering assembler commands. These command 
characters are described in Section 5.2, "Command 
Characters." 



5.1 BOH TO START MACRO ASSEMBLER 

Macro Assembler may be started in two ways. By the first 
method, you type the commands in response to individual 
prompts. By the second method, you type all commands on the 
line used to start Macro Assembler. 



Summary of Methods to Start Macro Assembler 



Method 1 
Method 2 



MASM 

MASM <source>,<object>,<listing> , 
<cross-ref> [/switch. . .] 
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5.1.1 Method 1: Prompts 

Type: 

MASM 

Macro Assembler will be loaded into memory- Then, Macro 
Assembler returns a series of four text prompts that appear 
one at a time. You answer the prompts as commands to Macro 
Assembler to perform specific tasks. 

At the end of each line, you may specify one or more 
switches, each of which must be preceded by a forward slash 
(/). 

The command prompts are summarized here and described in 
more detail in Section 5.3, "Macro Assembler Command 
Prompts." 



Summary of Command Prompts 
PROMPT 



RESPONSES 



Source filename [.ASM]: 



List .ASM file to be 
assembled. (There is no 
default: a filename 
response is required.) 



Object filename [source. OBJ 



List filename for 

relocatable object code. 

(The default is 
source- filename. OBJ) 



Source listing [NUL.LST] : 



List filename for listing. 
(The default is no listing 
file.) 



Cross reference [NUL.CRF] 



List filename for 
cross-reference file (used 
with MS-CREF to create a 
cross-reference listing) . 
(The default is no 
cross-reference file.) 
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5.1.2 Method 2: CoimBand Line 

Type: 

MASM <source> ,<object> ,<listing>,<cross-ref> [/switch. . . ] 

Macro Assembler will be loaded into memory. Then Macro 
Assembler immediately begins assembly. The entries 
following MASM are responses to the command prompts. The 
entry fields for the different prompts must be separated by 
commas . 

where: source is the source filename 

object is the name of the file to receive the 
relocatable output 

1 is ting is the name of the file to receive the 
listing 

cross-ref is the name of the file to receive the 
cross-reference output 

/switch are optional switches, which may be placed 
following any of the response entries (just before 
any of the commas or after the the <cross-ref>, as 
shown) . 

To select the default for a field, simply enter a second 
comma without space in between (see the example below) . 

Example: 

MASM FUN,,FUN/D/X,FUN 

This example causes Macro Assembler to be loaded, then 
causes the source file FUN. ASM to be assembled. Macro 
Assembler then outputs the relocatable object code to a file 
named FUN. OBJ (default caused by two commas in a row), 
creates a listing file named FUN.LST for both assembly 
passes but with false conditionals suppressed, and creates a 
cross-reference file named FUN.CRF. If names were not 
listed for listing and cross-reference, these files would 
not be created. If listing file switches are given but no 
filename, the switches are ignored. 
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5.2 MACRO ASSEMBLER COMMAND CHARACTERS 

Macro Assembler provides two command characters. 

Semicolon Use a single semicolon (;), followed 
immediately by a carriage return, at any 
time after responding to the first prompt 
(from Source filename: on) to select 
default responses to the remaining prompts. 
This feature saves time and eliminates the 
need to enter a series of carriage returns. 



NOTE 

Once the semicolon has been entered, 
you can no longer respond to any of 
the prompts for that assembly. 
Therefore, do not use the semicolon 
to skip over some prompts. For 
this, use the <RETURN> key. 



Example: 

Source filename [.ASM]: FUN 
Object filename (FUN. OBJ 1 : 

The remaining prompts will not appear, and 
Macro Assembler will use the default values 
(including no listing file and no 
cross-reference file) . 

To achieve the same result, you could type: 

Source filename [.ASM]: FUN ; 

This response produces the same files as the 
previous example. 



CONTROL-C Use <CONTROL-C> at any time to abort the 
assembly. If you enter an erroneous 
response, such as the wrong filename or an 
incorrectly spelled filename, you must press 
<CONTROL-C> to exit Macro Assembler. You 
can then restart Macro Assembler. If the 
error has been typed and not entered, you 
may delq^te the erroneous characters, but for 
that line only. 
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5.3 MACRO ASSEMBLER COMMAND PROMPTS 

Macro Assembler is commanded by entering responses to four 
text prompts. When you have typed a response to the current 
prompt, the next appears. When the last prompt has been 
answered. Macro Assembler begins assembly automatically 
without further command. When assembly is finished. Macro 
Assembler exits to the operating system. When the operating 
system prompt is displayed. Macro Assembler has finished 
successfully. If the assembly is unsuccessful. Macro 
Assembler displays the appropriate error message. 

Macro Assembler prompts you for the names of source, object, 
listing," and cross-reference files. 

All command prompts accept a file specification as a 
response. You may type: 

A filename only 

A device designation only 

A filename and an extension 

A device designation and filename, or 

A device designation, filename, and extension. 

Do not type only a filename extension. 

The following is a discussion of the command prompts that 
are displayed when you start Macro Assembler with Method 1: 

Sou^rce file name [ .ASM ] i 

Type the filename of your source program. Macro 
Assembler assumes by default that the filename 
extension is .ASM, as shown in square brackets in 
the prompt text. If your source program has any 
other filename extension, you must specify it along 
with the filename. Otherwise, the extension may be 
omitted . 



O bjec t filename [source .OBJ] ; 

Type the filename you want to receive the generated 
olaject code. If you simply press the carriage 
• return key when this prompt appears, the object 
file will be given the same name as the source 
file, but with the filename extension .OBJ. If you 
want your object file to have a different name or a 
different filename extension, you must type your 
choice in response to this prompt. If you want to 
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change only the filename but keep the .OBJ 
extension, type the filename only. To change the 
extension only, you must type both the filename and 
the extension. 



Sourc e list ing [NUL.LST] : 

Type the name of the file you want to receive the 
source listing. If you press the carriage return 
key. Macro Assembler does not produce this listing 
file. If you type a filename only, the listing is 
created and placed in a file with the name you type 
plus the filename extension .LST. You may also 
type your own extension. 

The source listing file will contain a list of all 
the statements in your source program and will show 
the code and offsets generated for each statement. 
The lifting will also show any error messages 
qonorated during the session. 



C^ross r efere nce [NU L.CRF] ; 

Type the name of the file you want to receive the 
cross-reference file. If you press only the 
<RETURN> key. Macro Assembler does not produce this 
cross-reference file. If you type a filename only, 
the cross-reference file is created and placed in a 
file with the name you type plus the filename 
extension .CRF. You may also type your own 
extension. 

The cross-reference file is used as the source file 
for the Microsoft CREF Cross-Ref erence Utility 
(MS-CREF) . MS-CREF converts this cross-reference 
file into a cross-reference listing, which you can 
use to aid you during program debugging. 

The cross-reference file contains a series of 
control symbols that identify records in the file, 
MS-CREF uses these control symbols to create a 
listing that shows all occurrences of every symbol 
in your program. The occurrence that defines the 
symbol is also identified. 
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5.4 MACRO ASSEMBLER CCMMANO SWITCHES 

The three Macro Assembler switches control assembler 
functions. Switches must be typed at the end of a prompt 
response, regardless of which method is used to start Macro 
Assembler. Switches may be grouped at the end of any one of 
the responses, or may be scattered at the end of several. 
If more than one switch is typed at the end of one response, 
each switch must be preceded by a forward slash (/) . Do not 
specify only a switch as a response to a command prompt. 



Switch Function 

/D Produces a source listing on both assembler passes. 
The listings will, when compared, show where in the 
program phase errors occur and will, possibly, give 
you a clue to why the errors occur. The /D switch 
does not take effect unless you command Macro 
Assembler to create a source listing (type a 
filename in response to the Source listing: 
command prompt) . 



/O Outputs the listing file in octal radix. The 
generated code and the offsets shown on the listing 
will all be given in octal. The actual code in the 
object file will be the same as if the /O switch 
were not given. The /O switch affects only the 
listing file. 



/X Suppresses the listing of false conditionals. If 

your program contains conditional blocks, the 

listing file will show the source statements, but 
no code if the condition evaluates false. To avoid 

the clutter of conditional blocks that do not 

generate 6ode, use the /X switch to suppress the 
blocks that evaluate false from your listing. 

The /X switch does not affect any block of code in 
your file that is controlled by either the .SFCOND 
or .LFCOND directives. 
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If your source program contains the .TFCOND 
directive, the /X switch has the opposite effect. 
That is, normally the .TFCOND directive causes 
listing or suppressing of blocks of code that it 
controls. The first .TFCOND directive suppresses 
false conditionals, the second restores listing of 
false conditionals, and so on. When you use the /X 
switch, false conditionals are already suppressed. 
When Macro Assembler encounters the first .TFCOND 
directive, listing of false conditionals is 
restored. When the second .TFCOND is encountered 
(and the /X switch is used) , false conditionals are 
again suppressed from the listing. 

Of course, the /X switch has no effect if no 
listing is created. See additional discussion 
under the .TFCOND directive in Section 4.2.4, 
"Listing Directives." 

The following chart illustrates the various effects 
of the conditional listing directives in 
combination with the /X switch. 



ASSEMBLING A MACRO ASSEMBLER SOURCE FILE 



Page '^-9 



Pseudo-op ^ /^ Z^ 

(none) ON OFF 



SFCOND 



LFCOND 



TFCOND 



.TFCOND 



SFCOND 



.TFCOND 
.TFCOND 



OFF OFF 



ON ON 



OFF ON 



ON OFF 



OFF 



OFF 
ON 



OFF 



ON 
OFF 



.TFCOND 



OFF 



ON 



Summary oE Command Switches 
SWITCH ACTION 



/D 
/O 
/X 



Produce a listing on both assembler 
passes. 



Show generated object code and offsets 
in octal radix on listing. 



Suppress the listing of false 
conditionals. Also used with the 
.TFCOND directive. 
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5.5 FORMATS OF LISTINGS AND SYMBOL TABLES 

The source listing produced by Macro Assembler (created when 
you specify a filename in response to the Source listing: 
prompt) is divided into two parts. 

The first part of the listing shows; 

The line number for each line of the source file, 
if a cross-reference file is also being created. 

The offset of each source line that generates code. 

The code generated by each source line. 

A plus sign (+) , if the code came from a macro, or 
a letter C, if the code came from an INCLUDE file. 

The source statement line. 

The second part of the listing shows: 

Macros — name and length in bytes 

Structures and records — name, width and fields 

Segments and groups — name, size, align, combine, 
and class 

Symbols — name, type, value, and attributes 

The number of warning errors and severe errors 



5.5.1 Program Listing 

The program portion of the listing is essentially your 
source program file with the line numbers, offsets, 
generated code, and {where applicable) a plus sign to 
indicate that the source statements are part of a macro 
block, or a letter C to indicate that the source statements 
are from a file input by the INCLUDE directive. 

If any errors occur during assembly, the error message will 
be printed directly below the statement where the error 
occurred . 
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Part of a listing file follows this discussion, with notes 
explaining what the various entries represent. 

The comments have been moved down one line because of format 

restrictions. If you print your listing on 132 

column-paper, the comments shown here will easily fit on the 
same line as the rest of the statement. 
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Explanatory notes are spliced into the listing at points of 
special interest. ^ 

Summary o£ Listing Symbols 

R = Linker resolves entry to left of R 

E = External 

= Segment namcr group name, or segment variable 

used in MOV AX,< >, DD < >, JMP < >, 

and so on. 

= = Statement has an EQU or = directive 

nn: = Statement contains a segment override 

nn/ = REPxx or LOCK prefix instruction. Example: 

003C F3/ A5 REP MOVSW ;move DStSI to ES:DI 

; until CX=0 



I J 



[ = DUP expression; XX is the value in parentheses 
XX following DUP; for example: DUP{?) places ?? 
] where xx is shown here 

+ = Line comes from a macro expansion 

C = Line comes from file named in INCLUDE directive 
statement 
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Microsoft Macro Assembler l-Dec-81 PAGE 1-3 
EXTX PASCAL entry for initializing programs 



0000 STACK SEGMENT WORD STACK 'STACK' 

= 0000 HEAPbeg EQlKry THIS BYTE 

^ Indicates EQU or = directive 

;Base of heap before init 
0000 14 ( DB 20 DUP (?)«. 

??<-Shows value in parentheses -^ 

1 

Indicates DUP expression 
= 0014 SKTOP EQU THIS BYTE 
0014 STACK ENDS 



0000 



MAINSTARTUP SEGMENT 'MEMORY' 

DGROUP GROUP DATA, ST ACK <CONST , HEAP , MEMORY 
ASSUME CS:MAINSTARTUP,DS: DGROUP, 
ES : DGROUP , SS : DGROUP 

PUBLIC BEGXQQ ;Main entry 



0000 
0000 

0003 
0005 


BEGXQQ 
B8 R 

8E D8 

8C 06 0022 R 


PROC 
MOV 

MOV 

MOV 


FAR 

AX, DGROUP 

;Get data segment value 

DS,AX ;Set DS seg 

CESXQQ,ES N^ 


Generated Name 
Offset 


— 1 ^^* Si 
Action Expression Comment 



OOOC 26t 8B IE 0002 



MOV BX,ES^ ;Highest 

;paragraph 

•Segment override-! 



ASSEMBLING A MACRO ASSEMBLER SOURCE FILE 



Page 5-14 



Microsoft Macro Assembler l-Dec-81 PAGE 1-4 
ENTX PASCAL entry for initializing programs 



0011 2B D8 

0013 81 FB 1000 

0017 7E 03 

0019 BB 1000 

OOIC 



OOIC DlrE3 

OOIE Dl -E3 

0020 Dl -E3 

0022 Dl -ES 



SUB BX,AX ;Get I paras for DS 

CMP BX,4096 ;More than 64K? 

JLE SMLSTK ;No, use what we have 

MOV BX,4096 ;Can only address 64k 



^, 



SMLSTK: +> REPT 4 <- 
SHL BX r 1 

;Convert para 
ENDM 

SHL BX , 1 

;Convert para 
SHL BX,1 

;Convert para 
SHL BX , 1 

J Con vert para 
SHL BX,1 

;Convert para 



macro ^these lines 



*-> macro 



block 



from macro directive 



to offset 

to offset 

to offset 

to offset 

to offset 

— > number of 
repetitions 



0024 8B E3 MOV SP,BX 

;Set stack to top of memory 



0069 EA 0000 



006E 



JMP 



FAR PTR STARTmain 



signal to linker 



segment variable 



linker resolves; indicates segment name, group name, 

or segment variable used in MOV AX,< >; 

DD < >; JMP < >,etc. (See other 

examples in this listing.) 



BEGXQQ 



ENDP 



007E MAIN_STARTUP ENDS 

0000 ENTXCM SEGMENT WORD 'CODE* 

ASSUME CS: ENTXCM 

PUBLIC ENDXQQ,DOSXQQ 
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Microsoft Macro Assembler l-Dec-81 PAGE 1-5 
ENTX PASCAL entry for initializing programs 



0000 STARTmain 
0000 9A 0000 E 



0005 ENDXQQ 

0005 9A 0000 

OOOA 9A 0000 — 

OOOF 9A 0000 



E 
E 

E <- 



PROC FAR ;This code remains 

CALL ENTGQQ 
;call main program 

LABEL FAR 

; termination entry point 

CALL ENDOQQ 
;user system termination 

CALL ENDYQQ 
; close all open files 
CALL ENDUQQ 

;file system 
; termination 



0014 C7 06 0020 R 0000 



t 

>ffset 



MOV 



J 



DOSOFF , 



linker External 

signal; symbol 

goes with 

number to left; shows DOSOFF is in segment 



00 2E 0020 R JMP 

00 IE STARTmain ENOP 



DWORD PTR DOSOFF 
; return to DOS 



0037 



BNTXCM 



END 



ENDS 
BEGXQQ 
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5.5.2 Differences Between Pass 1 And Pass 2 Listings 



If you specify the /D switch when you run Macro Assembler to 
assemble your file, the assembler produces a listing for 
both passes. The option is especially helpful for finding 
the source of phase errors. 

The following example was taken from a source file that 
assembled without reporting any errors. When the source 
file was reassembled using the /D switch, an error was 
produced on pass 1, but not on pass 2 (which is when errors 
are usually reported) . 

Example: 

During Pass 1 a jump with a forward reference produces: 

0017 7E 00 JLE SMLSTK ;No, use what we have 

Error 9:Symbol not defined 

0019 BB 1000 MOV BX,4096 ;Can only address 64k 

00 IC SMLSTK: REPT 4 



During Pass 2 this same instruction is fixed up and does not 
return an error. 

0017 7E 03 JLE SMLSTK ;No, use what we have 

0019 BB 1000 MOV BX,4096 ;Can only address 64k 

00 IC SMLSTK: REPT 4 



Notice that the JLE instruction's code now contains 03 
instead of 00? this is a jump of 3 bytes. 

The same amount of code was produced during both passes, so 
there was no phase error. The only difference in this case 
is one of content instead of size, 
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5.5.3 Symbol Table Pornat 

The symbol table portion of a listing separates all 
"symbols" into their respective categories, showing 
appropriate descriptive data. This data gives you an idea 
how your program is using various symbolic values. and is 
useful when you debug. 

Also, you can use a cross-reference listing, produced by 
MS-CREF, to help you locate uses of the various "symbols" in 
your program. 

On the next page is a complete symbol table listing. 
Following the complete listing, sections from different 
symbol tables are shown with explanatory notes. 

For all sections of symbol tables, this rule applies: if 
there are no symbolic values in your program for a 
particular category, the heading for the category will be 
omitted from the symbol table listing. For example, if you 
use no macros in your program, you will not see a macro 
section in the symbol table. 
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Microsoft Macro Assembler MACRO 
Assembler date PAGE Symbols-1 
CALLER - SAMPLE ASSEMBLER ROUTINE (EXMPlM.ASM) 



Macros: 



Name 



Length 



BIOSCALL 0002 

DISPLAY 0005 

DOSCALL 0002 

KEYBOARD 0003 

LOCATE 0003 

SCROLL 0004 



Structures and records: 



Name 




Width 
Shift 


# fields 
Width Mask 


Initial 


PARMLIST . . 




00 IC 
0000 
0001 
0002 
OOIB 


0004 






BUFSIZE. . 






NAMES I ZE . 






NAMETEXT . 






TERMINATOR 


■ • • • 




Segments and 


groups: 










Name 




Size 


align 


combine 


class 


CSEG .... 




0044 
0200 
0031 


PARA 
PARA 
PARA 


PUBLIC 

STACK 

PUBLIC 


•CODE' 


STACK. . . . 
WORKAREA . . 


.... 


' STACK • 
•DATA' 



Symbols: 



Name 



Type 



Value Attr 



CLS 

maxchar! 

MESSG . . 
PARMS . . 
RECEIVR. 
START . . 



N PROC 


0036 


CSEG Length -OOOE 


Number 


0019 




L BYTE 


OOIC 


WORKAREA 


L OOIC 


0000 


WORKAREA 


L FAR 


0000 


External 


F PROC 


0000 


CSEG Length -0036 



Warning Severe 
Errors Errors 
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Macros: 



Name 

BIOSCALL . . 

DISPLAY. . . 

DOSCALL. . . 

KEYBOARD . . 

LOCATE . . . 

SCROLL . . . 



Length <- 

0002 
0005 
0002 
0003 
0003 
0004 



■number of 32-byte blocks 
macro occupies in memory 



names of macros 



This section of the symbol table tells you the names of your 
macros and how big they are in 32-byte block units. In this 
listing, the macro DISPLAY is 5 blocks long or (5 X 32 bytes 
=) 160 bytes long. 
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Structures and records: 
Example for Structures 



Name 



PARMLIST •. 

BUFSIZE. . . . . . 

NAMESIZE 

NAMETEXT 

TERMINATOR .... 

I — field names of 
PARMLIST Structure 



Width # fields < — * 
Shift Width Mask Initial 



00 IC 
0000 
0001 
0002 
OOIB 



-i0004 

\ \ \*** 



Offset of field 
into structure 



The number of bytes 
wide of Structure 



Example for Records 
Name 



Width #' fields 

Shift Width Mask Initial 



BAZ, 



FLDl 
FLD2 

FLD3 

BAZl . 

BZl. 



BZ2, 



r>0008 0003 < — number of fields 











in Record 


0006 


0002 


OOCO 0040 


0003 


"■ 


0003 




0038 0000<— initial 
value 


0000 




0003 




0007 0003 


OOOB 




0002 


^MASK of field 


0003 




0008 


07F8 0400 maximum 
value 


0000«- 


0003 


0007 0002 


shift . nu 


mber of 


count bits in field 


to I 


•1 


ght 







number of 
bits in Record 



* This line applies to Structure Names (begin in column 1) 
** This line for fields of Records (indented) . 
***Number of fields in Structure. 



This section lists your Structures and/or Records and their 

fields. The upper line of column headings applies to 

Structure names. Record names, and field names of 

Structures. The lower line of column headings applies to 
field names of Records. 
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Width (upper line) shows the number of bytes your 
Structure occupies in memory. 

1 fields shows how many fields comprise your 
Structure. 



For Records: 



Width (upper line) shows the number of bits the 
Record occupies. 

t fie lds shows how many fields comprise your 
Record. 



For Fields of Structures: 

Shift shows the number of bytes the fields are 
offset into the Structure. 

The other columns are not used for fields of 
Structures. 

For Fields of Records: 

Shift is the shift count to the right. 

Width (lower line) shows the number of bits this 
field occupies. 

Mask shows the maximum value of the record, 

expressed in hexadecimal, if one field is masked 

and ANDed (the field is set to all I's and all 
other fields are set to all O's). 

Using field BZl of the Record BAZl above to 
illustrate: 



000001 lllllllOOO *-MASK =. 07F8 











1 




















15 11 


10 




4 


3 
^1 




1 




"1 

shift ( 










WI 


DTH 


= 


00 


08 
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Initial shows the value specified as the initial value for 
the field, if any. 

When naming the field, you specified: 
fieldname:! = value 

Fieldname is the name of the field 

# is the width of the field in bits 

Value is the initial value you want this field to 
hold. The symbol table shows this value as if it 
is placed in the field and all other fields are 
masked (equal 0) . Using the example and diagram 
from above: 



00000 100 010 Initial>0400 



Initial ^ BOM 

80H = 128 decimal 



Segments and groups: 



Name S 


ize 


align combine cl 


ass 








/ ca 


lied Private 








/ in MS 


-LINK manual 


AAAXQQ . . 


0000 


WORD 


NONE 


'CODE'<- 


•-segment 


DGROUP. . 
DATA . 




GROUP < 
0024 








rt »-/-Mir^ 




WORD 


PUBLIC 


• DATA ' 


9' 


^^f 


STACK. 




0014 


WORD 


STACK 


' STACK • 




segments 


CONST . 




0000 


WORD 


PUBLIC 


'CONST' 




of 


HEAP . 




0000 


WORD 


PUBLIC 


•MEMORY' 




DGROUP 


MEMORY 




0000 


WORD 


PUBLIC 


•MEMORY' 






ENTXCM . 




0037 


WORD 


NONE 


'CODE' 




MAIN STARTUI 


' . 007E 


PARA 


NONE 


' MEMORY ' 
entries 






length 

of 
segment 


statement line 
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For Groups: 

The name of the group will appear under the Name column, 
beginning in column 1 with the applicable Segment names 
indented 2 spaces. The word Group will appear under the 
Size column. 

For Segments: 

The segment names may appear in column 1 (as here) if you do 
not declare them part of a group. If you declare a group, 
the segment names will appear indented under their group 
name. 

For all Segments, whether a part of a group or not: 

Size is the number of bytes the Segment occupies. 

Align is the type of boundary where the segment 
begins: 

PAGE >= page - address is xxxOOH (low byte » 0) ; 
begins on a 256-byte boundary 

PARA a paragraph - address is xxxxOH 
(low nibble » 0); default 

WORD a word - address is xxxxeH 
(e > even number; 
low bit of low byte « 0) 
bit map - |x|x|x|x|x|x|x|o| 

BYTE B byte - address is xxxxxH (anywhere) 



Combine describes how the Microsoft LINK Linker 
Utility will combine the various segments. (See. 
the Microsoft LINK Linker Utility Manual for a full 
description.) 

Class is the class name under which MS-LINK will 
combine segments in memory. (See MS-LINK Linker 
Utility Manual and Chapter 9 of the MS-DOS User * a 
Guide for a full description.) 
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Symbols: 






















Name 




Type 


Value Attr 


FOO. . . 






Number 0005 






FOOl . . 






Text 


1. 


234 






F002 . . . 






Number 0008 




all formed by 


F003 . . . 






Alias FOO 




EQU or = 


F004 . . , 






Text 


5[BP1 [DI] 




directive 


F005 . . . 


• • 




Opcode 








Symbols: 
















Name 


Type 


Value 


Attr 




BEGHQQ . . 


• • 


L 


WORD 


0012 


DATA 


Global 


BEGOQQ . . 






L 


FAR 


0000 


External 


BEGXQQ . . 






P 


PROC 


0000 


MAIN STARTUP Global Length=006E 


CESXQQ . 






L 


WORD 


0022 


DATA 


Global 




1 


CLNEQQ . 






L 


WORD 


0002 


DATA 


Global l-length 


CRCXQQ . 






L 


WORD 


OOIC 


DATA 


Global of PROC 


CRDXQQ . 






L 


WORD 


OOIE 


DATA 


Global 


CSXEQQ . 






L 


WORD 


0000 


DATA 


Global 


CURHQQ . 






L 


WORD 


0014 


DATA 


Global 


DOSOFF . 






L 


WORD 


0020 


DATA 




DOSXQQ . 






F 


PROC 


OOIE 


ENTXCM 


Global Length =0019 


ENDHQQ . 






L 


WORD 


0016 


DATA 


Global 


ENDOQQ . 






L 


FAR 


0000 




External 


ENDUQQ . 






L 


FAR 


0000 




External 


ENDXQQ . 






L 


FAR 


0005 


ENTXCM 


Global 


ENDYQQ . 






L 


FAR 


0000 




External 


ENTGQQ . 






L 


FAR 


0000 




External 


FREXQQ . 






F 


PROC 


006E 


MAIN STARTUP Global Length=0010 


HDRFQQ . 






L 


WORD 


0006 


DATA 


Global 


HDRVQQ . 






L 


WORD 


0008 


DATA 


Global 


HEAPBEG , 
HEAPLOW. 






BYTE 
BYTE 


0000 
0000 


STACK 
HEAP ^ 








E ' showing segment 


INIUQQ . 






L 


FAR 


0000 




External 




PNUXQQ . 






L 


WORD 


0004 


DATA 


Global 




RECEQQ . 






L 


WORD 


0010 


DATA 


Global 




REFEQQ . 






L 


WORD 


oooc 


DATA 


Global , 




REPEQQ . 






L 


WORD 


OOOE 


DATA 


Global / 


RESEQQ . 
SKTOP . . 






L 


WORD 


OOOA 
0014 


DATA 


Global / 






BYTE 


STACK 




SMLSTK . 






L 


NEAR 


OOIC 


MAIN STARTUP 


STARTMAIN . 






F 


PROC 


0000 


ENTXCM 


Length=001E 


STKBQO . 






L 


WORD 


0018 


DATA 


Global 


STKHQQ . 






L 


WORD 


OOIA 


DATA 


Global 





G 



If Macro Assembler knows this length as one of the 
type lengths (BYTE, WORD, DWORD, QWORD, 
TBYTE) , it shows that type name here. 



ASSEMBLING A MACRO ASSEMBLER SOURCE FILE Page 5-25 

This section lists all other symbolic values in your program 
that do not fit under the other categories. 

Type shows the symbol's type: 
L » Label 
F = Far 
N = Near 

PROC = Procedure 
Number 
Alias 
Text 
Opcode 



all defined by EQU or = directive 



These entries may be combined to form the various 
types shown in the example. 

For all procedures, the length of the procedure is 
given after its attribute (segment). 

You may also see an entry under Type like: 

L 0031 
This entry results from code such as the following: 

BAZ LABEL FOO 

where FOO is a STRUC that is 31 bytes long. 

BAZ will be shown in the symbol table with the L 
0031 entry. Basically, Number (and some other 
similar entries) indicates that the symbol was 
defined by an EQU or = directive. 

Value (usually) shows the numeric value the symbol 
represents. (In some cases, the Value column will show some 
text — when the symbol was defined by EQU or = directive.) 

Attr always shows the segment of the symbol, if known. 
Otherwise, the Attr column is blank. Following the segment 
name, the table will show either External, Global, or a 
blank (which means not declared with either the EXTRN or 
PUBLIC directive) . The last entry applies to PROC types 
only. This is a length = entry, which is the length of the 
procedure. 
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I£ Type is Number » Opcode , AliaSr or Text , the Symbols 
section of the listing will be structured differently. 
Whenever you see one of these four entries under Type, the 
symbol was created by. an BQU directive or an ■ directive. 
All information that follows one of these entries is 
considered its "value," even if the "value" is simple text. 

Bach of the four types shows a value as follows: 

Number shows a constant numeric value. 

Opcode shows a blank. The symbol is an alias for 
an instruction mnemonic. 

Sample directive statement: FOG BQO AOO 

Alias shows a symbol name which the named symbol 
equals. 

Sample directive statement: fOO BQO BAX 

Text shows the "text" the symbol represents. 
"Text" is any other operand to an BQO directive 
that does not fit one of* the other three categories 
above. 

Sample directive statements: 
600 BQU *flOW* 
BAZ EQO DS:8(BX] 
ZOO BQO 1.234 



Contents 



Chapter 6 8087 Support 

6.1 Switches 6-1 



CHAPTER 6 
8087 SUPPORT 



Macro Assembler supports standard Intel 8087 instructions 
and operands. A list of the instructions and opcodes can be 
found in Appendix C of this manual. 



6.1 SWITCHES 

There are two switches that are used when running Macro 
Assembler with an 8087. These switches are /R <for Real) 
and /E (for Emulate). The /R and /E switches are described 
below. 

Switch Function 

/R Use the /R switch when the code being produced by 
Macro Assembler is going to be run on a real 8087 
machine (not an emulated machine) . Code produced 
with the /R switch will only run on real 8087 
machines. 



/E Use the /E switch when the code being produced by 
Macro Assembler is going to be run on an emulated 
8087 machine. Code produced with the /E switch 
will also run on real 8087 machines with the 
appropriate emulator library. 

The emulator library is provided with some MS-DOS language 
products. It contains specific 8087 emulation routines. 
Refer to your language compiler user's guide for information 
on the emulator library that has been provided. If your 
code is going to run on an emulated 8087 machine, you must 
specify .the appropriate emulator library when you link your 
code with MS-LINK. If the library is not specified, MS-LINK 
will return errors for those unresolved symbols that are 
defined in the emulator library. 
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CHAPTER 7 
MACRO ASSEMBLER MESSAGES 



Most o£ the messages output by Macro Assembler are error 
messages. The nonerror messages output by Macro Assembler 
are the banner Macro Assembler displays when £irst started, 
the command prompt messages , and the end of (successful) 
assembly message. These nonerror messages are classified 
here as operating messages. The error messages are 
classified as assembler errors, I/O handler errors, and 
runtime errors. 



7.1 OPERATING MESSAGES 

Banner Message and Command Prompts: 

Macro Assembler v2.0 Copyright (C) Microsoft, Inc. 

Source filename [.ASMl: 
Object filename (source. OBJl : 
Source listing [NUL.LST] : 
Cross reference (NUL.CRF] : 

End of Assembly Message: 

Warning Fatal 

Errors Errors 

n n (n»number of errors) 

(your disk operating system's prompt) 
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7.2 ERROR MESSAGES 

If the assembler encounters errors, error messages are 
output, along with the numbers of warning and fatal errors, 
and control is returned to your disk operating system. The 
message is output either to your terminal screen or to the 
listing file if you command one be created. 

Error messages are divided into three categories: assembler 
errors, I/O handler errors, and runtime errors. In each 
category, messages are listed in alphabetical order with a 
short explanation where necessary. At the end of this 
chapter, the error messages are listed in a single numerical 
order list but without explanations. 



Assenbler Errors 



Already defined locally {Code 23) 

Tried to define a symbol as EXTERNAL that had 
already been defined locally. 

Already had ELSE clause (Code 7) 

Attempt to define an ELSE clause within an existing 
ELSE clause (you cannot nest ELSE without nesting 
IF. . .ENDIF) . 

Already have base register (Code 46) 

Trying to double base register. 

Already have index register (Code 47) 

Trying to double index address 

Block nesting error (Code 0) 

Nested procedures, segments, structures, macros, 
IRC, IRP, or REPT are not properly terminated. An 
example of this error is close of an outer level of 
nesting with inner level (s) still open. 
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Byte register is illegal (Code 58) 

Use of one of the byte registers in context where 
it is illegal. For example, PUSH AL. 

Can't override ES segment (Code 67) 

Trying to override the ES segment in an instruction 
where this override is not legal. For example, 
store string. 



Can't reach with segment reg (Code 68) 

There is no ASSUME that makes the variable 
reachable. 



Can't use EVEN on BYTE segment (Code 70) 

Segment was declared to be byte segment and attempt 
to use EVEN was made. 



Circular chain of EQU aliases (Code 83) 

An alias EQU eventually points to itself. 

Constant was expected (Code 42) 

Expecting a constant and received something else. 

CS register illegal usage (Code 59) 

Trying to use the CS register illegally. For 
example, XCHG CS,AX. 

Directive illegal in STRUG (Code 78) 

All statements within STRUC blocks must either be 
comments preceded by a semicolon (;), or one of the 
Define directives. 



Division by or overflow (Code 29) 

An expression is given that results in a divide by 
0. 
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DUP is too large for linker (Code 74) 

Nesting of DUP's was such that too large a record 
was created for the linker. 



8087 opcode can't be emulated (Code 84) 

Either the 8087 opcode or the operands you used 
with it produce an instruction that the emulator 
cannot support. 

Extra characters on line (Code 1) 

This occurs when sufficient information to define 
the instruction directive has been received on a 
line and superfluous characters beyond are 
received. 



Field cannot be overridden (Code 80) 

In a STRUC initialization statement, you tried to 
give a value to a field that cannot be overridden. 



Forward needs override (Code 71) 

This message is not currently used. 

Forward reference is illegal (Code 17) 

Attempt to forward reference something that must be 
defined in pass 1. 

Illegal register value (Code 55) 

The register value specified does not fit into the 
"reg" field (the reg field is greater than 7) . 

Illegal size for item (Code 57) 

Size of referenced item is illegal. For example, 
shift of a double word. 
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Illegal use of external (Code 32) 

Use of an external in some illegal manner. For 
example, DB M DUP(?) where M is declared external. 

Illegal use of register (Code 49) 

Use of a register with an instruction where there 
is no 8086 or 8088 instruction possible. 

Illegal value for DUP count (Code 72) 

DUP counts must be a constant that is not or 
negative. 



Improper operand type (Code 52) 

Use of an operand such that the opcode cannot be 
generated. 

Improper use of segment reg (Code 61) 

Specification of a segment register where this is 
illegal. For example, an immediate move to a 
segment register. 

Index displ. must be constant (Code 54) 
Illegal use of index display. 

Label can't have seg. override (Code 65) 
Illegal use of segment override. 

Left operand must have segment (Code 38) 

Used something in right operand that required a 
segment in the left operand. (For example, ":.") 

More values than defined with (Code 76) 

Too many fields given in REC or STRUC allocation. 
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Must be associated with code (Code 45) 

Use of data related item where code item was 
expected. 

Must be associated with data (Code 44) 

Use of code related item where data related item 
was exected. For example, MOV AX,<code-label>. 



Must be AX or AL (Code 60) 

Specification of some register other than AX or AL 
where only these are acceptable. For example, the 
IN instruction. 

Must be index or base register (Code 48) 

Instruction requires a base or index register and 
some other register was specified in square 
brackets, f ] , 



Must be declared in pass 1 (Code 13) 

Assembler expecting a constant value but got 
something else. An example of this might be a 
vector size being a forward reference. 

Must be in segment block (Code 69} 

Attempt to generate code when not in a segment. 

Must be record field name (Code 33) 

Expecting a record field name but got something 
else. 

Must be record or field name (Code 34) 

Expecting a record name or field name and received 
something else. 

Must be register (Code 18) 

Register unexpected as operand but you furnished a 
symbol — was not a register. 
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Must be segment or group (Code 20) 

Expecting segment or group and something else was 
specified. 

Must be structure field name (Code 37) 

Expecting a structure field name but received 
something else. 

Must be symbol type (Code 22) 

Must be WORD, DW, QW, BYTE, or TB but received 
something else. 

Must be var, label or constant (Code 36) 

Expecting a variable, label, or constant but 
received something else. 

Must have opcode after prefix (Code 66) 
\ 

y Use of one of the prefix instructions without 

specifying any opcode after it. 

Near JMP/CALL to different CS (Code 64) 

Attempt to do a NEAR jump or call to a location in 
a different CS ASSUME. 

No immediate mode (Code 56) 

Immediate mode specified or an opcode that cannot 
accept the immediate. For example, PUSH. 

No or unreachable CS (Code 62) 

Trying to jump to a label that is unreachable. 

Normal type operand expected (Code 41) 

Received STRUCT, FIELDS, NAMES, BYTE, WORD, or DW 
when expecting a variable label. 
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Not in conditional block (Code 8) 

An ENDIF or ELSE is specified without a previous 
conditional assembly directive active. 

Not proper align/combine type (Code 25) 

SEGMENT parameters are incorrect. 

One operand must be const (Code 39) 

This is an illegal use of the addition operator. 

Only initialize list legal (Code 77) 

Attempt to use STRUC name without angle brackets , 
< >. 



Operand combination illegal (Code 63) 

Specification of a two-operand instrucion where the 
combination specified is illegal. 

Operands must be same or 1 abs (Code 40) 

Illegal use of the subtraction operator. 

Operand must have segment (Code 43) 

Illegal use of SEG directive. 

Operand must have size (Code 3$) 

Expected operand to have a size, but it did not. 

Operand not in IP segment (Code 51) 

Access of operand is impossible because it is not 
in the current IP segment. 

Operand types must match (Code 31) 

Assembler gets different kinds or sizes of 
arguments in a case where they must match. For 
example, MOV. 
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Operand was expected (Code 27) 

Assembler is expecting an operand but an operator 
was received. 



Operator was expected (Code 28) 

Assembler was expecting an operator but an operand 
was received. 



Override is of wrong type (Code 81) 

In a STRUC initialization statement, you tried to 
use the wrong size on override. For example, 
•HELLO' for DW field. 



Override with DUP is illegal (Code 79) 

In a STRUC initialization statement, you tried to 
use DUP in an override. 



Phase error between passes (Code 6) 

The program has ambiguous instruction directives 
such that the location of a label in the program 
changed in value between pass 1 and pass 2 of the 
assembler. An example of this is a forward 
reference coded without a segment override where 
one is required. There would be an additional byte 
(the code segment override) generated in pass 2 
causing the next label to change. You can use the 
/D switch to produce a listing to aid in resolving 
phase errors between passes (see Section 5.4, 
"Macro Assembler Command Switches"). 



Redefinition of symbol (Code 4) 

This error occurs on pass 2 and succeeding 
definitions of a symbol. 

Reference to mult defined (Code 26) 

The instruction references something that has been 
multi-defined. 
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Register already defined (Code 2) 

This will only occur if the assembler has internal 
logic errors. 

Register can't be forward ref (Code 82) 

Relative jump out of range (Code 53) 

Relative jumps must be within the range -128 +127 
of the current instruction, and the specific jump 
is beyond this range. 

Segment parameters are changed (Code 24) 

List of arguments to SEGMENT were not identical to 
the first time this segment was used. 



Shift count is negative (Code 30) 

A shift expression is generated that results in a 
negative shift count. 

Should have been group name (Code 12) 

Expecting a group name but something other than 
this was given. 

Symbol already different kind (Code 15) 

Attempt to define a symbol differently from a 
previous definition. 

Symbol already external (Code 73) 

Attempt to define a symbol as local that is already 
external. 



Symbol has no segment (Code 21) 

Trying to use a variable with SEG, and the variable 
has no known segment. 
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Symbol is multi-defined (Code 5) 

This error occurs on a symbol that is later 
redefined. 



Symbol is reserved word (Code 16) 

Attempt to use an assembler reserved word 
illegally. (For example, to declare MOV as a 
variable.) 



Symbol not defined (Code 9) 

A symbol is used that has no definition. 

Symbol type usage illegal (Code 14) 

Illegal use of a PUBLIC symbol. 

Syntax error (Code 10) 

The syntax of the statement does not match any 
recognizable syntax. 

Type illegal in context (Code 11) 

The type specified is of an unacceptable size. 

Unknown symbol type (Code 3) 

Symbol statement has something in the type field 
that is unrecognizable. 

Usage of ? (indeterminate) bad (Code 75) 

Improper use of the "?". For example, ?+5. 

Value is out of range (Code 50) 

Value is too large for expected use. For example, 
MOV AL,5000. 
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Wrong type of register (Code 19) 

Directive or instruction expected one type o£ 
register, but another was specified. For example, 
INC CS. 
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I/O Handler Errors 

These error messages are generated by the I/O handlers. 
These messages appear in a different format from the 
Assembler Errors; 

MASM Error — error-message-text 
in: filename 

The filename is the name of the file being handled when the 
error occurred. 

The error-message- text is one of the following messages: 

Data format (Code 114) 
Device full (Code 108) 
Device name (Code 102) 
Device offline (Code 105) 
File in use (Code 112) 
File name (Code 107) 
File not found (Code 110) 
File not open (Code 113) 
File system (Code 104) 
Hard data (Code 101) 
Line too long (Code 115) 
Lost file (Code 106) 
Operation (Code 103) 
Protected file (Code 111) 
Unknown device (Code 109) 
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Runtiae Errors 

These messages may be displayed as your assembled program is 
being executed. 



Internal Error 



Usually caused by an arithmetic check. If it 
occurs, notify Microsoft Corporation. 



Out of Memory 



This message has no corresponding number. Either 
the source was too big or too many labels are in 
the symbol table. 
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Nuoierical Order List of Error Messages 

Code Messag e 

Block nesting error 

1 Extra characters on line 

2 Register already defined 

3 Unknown symbol type 

4 Redefinition of symbol 

5 Symbol is multi-defined 

6 Phase error between passes 

7 Already had ELSE clause 

8 Not in conditional block 

9 Symbol not defined 

10 Syntax error 

11 Type illegal in context 

12 Should have been group name 

13 Must be declared in pass 1 

14 Symbol type usage illegal 

15 Symbol already different kind 

16 Symbol is reserved word 

17 Forward reference is illegal 

18 Must be register 

19 Wrong type of register 

20 Must be segment or group 

21 Symbol has no segment 

22 Must be symbol type 

23 Already defined locally 

24 Segment parameters are changed 

25 Not proper align/combine type 

26 Reference to mult defined 

27 Operand was expected 

28 Operator was expected 

29 Division by or overflow 

30 Shift count is negative 

31 Operand types must match 

32 Illegal use of external 

33 Must be record field name 

34 Must be record or field name 

35 Operand must have size 

36 Must be var, label or constant 

37 Must be structure field name 

38 Left operand must have segment 

39 One operand must be const 

40 Operands must be same or 1 abs 

41 Normal type operand expected 

42 Constant was expected 

43 Operand must have segment 

44 Must be associated with data 

45 Must be associated with code 

46 Already have base register 

47 Already have index register 

48 Must be index or base register 

49 Illegal use of register 

50 Value is out of range 
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51 Operand not in IP segment 

52 Improper operand type 

53 Relative jump out of range 

54 Index displ. must be constant 

55 Illegal register value 

56 No immediate mode 

57 Illegal size for item 

58 Byte register is illegal 

59 CS register illegal usage 

60 Must be AX or AL 

61 Improper use of segment reg 

62 No or unreachable CS 

63 Operand combination illegal 

64 Near JMP/CALL to different CS 

65 Label can't have seg . override 

66 Must have opcode after prefix 

67 Can't override ES segment 

68 Can't reach with segment reg 

69 Must be in segment block 

70 Can't use EVEN on BYTE segment 

71 Forward needs override 

72 Illegal value for DUP count 

73 Symbol already external 

74 DUP is too large for linker 

75 Usage of ? (indeterminate) bad (Code 75) 

76 More values than defined with 

77 Only initialize list legal 

78 Directive illegal in STRUC 

79 Override with DUP is illegal 

80 Field cannot be overridden 

81 Override is of wrong type 

82 Register can't be forward ref 

83 Circular chain of EQU aliases 

84 8087 opcode can't be emulated 

101 Hard data 

102 Device name 

103 Operation 

104 File system 

105 Device offline 

106 Lost file 

107 File name 

108 Device full 

109 Unknown device 

110 File not found 

111 Protected file 

112 File in use 

113 File not open 

114 Data format 

115 Line too long 
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APPENDIX A 
ASCII CHARACTER CODES 



Dec 


Hex 


CHR 


000 


OOH 


NUL 


001 


OIH 


SOH 


002 


02H 


STX 


003 


03H 


ETX 


004 


04H 


EOT 


005 


05H 


ENQ 


006 


06H 


ACK 


007 


07H 


BEL 


008 


08H 


BS 


009 


09H 


HT 


010 


OAH 


LF 


Oil 


OBH 


VT 


012 


OCH 


FF 


013 


ODH 


CR 


014 


OEH 


SO 


015 


OFH 


SI 


016 


lOH 


DLE 


017 


IIH 


DCl 


018 


12H 


DC 2 


019 


13H 


DC3 


020 


14H 


DC4 


021 


15H 


NAK 


022 


16H 


SYN 


023 


17H 


ETB 


024 


18H 


CAN 


025 


19H 


EM 


026 


lAH 


SUB 


027 


IBH 


ESCAPE 


028 


ICH 


FS 


029 


IDH 


GS 


030 


lEH 


RS 


031 


IFH 


US 


032 


20H 


SPACE 



Dec 


Hex 


CHR 


033 


21H 


I 


034 


22H 


If 


035 


23H 


« 


036 


24H 


$ 


037 


25H 


% 


038 


26H 


& 


039 


27H 


1 


040 


28H 


( 


041 


29H 


) 


042 


2AH 


* 


043 


2BH 


+ 


044 


2CH 


» 


045 


2DH 


- 


046 


2EH 


• 


047 


2FH 


/ 


048 


30H 





049 


31H 


1 


050 


32H 


2 


051 


33H 


3 


052 


34H 


4 


053 


35H 


5 


054 


36H 


6 


055 


37H 


7 


056 


38H 


8 


057 


39H 


9 


058 


3AH 


• 


059 


3BH 


; 


060 


3CH 


< 


061 


3DH 


s 


062 


3EH 


> 


063 


3FH 


? 


064 


40H 


@ 



Dec=deciinal, Hex=hexadecimal (H) , CHR=character . 

LF=Line Feed, FF=Form Feed, CR=Carriage Return, DEL=Rubout 



ASCII CHARACTER CODES 



Dec 


Hex 


CHR 


065 


41H 


A 


066 


42H 


B 


067 


43H 


C 


068 


44H 


D 


069 


45H 


E 


070 


46H 


F 


071 


47H 


G 


072 


48H 


H 


073 


49H 


I 


074 


4AH 


J 


075 


4BH 


K 


076 


4CH 


L 


077 


4DH 


M 


078 


4EH 


N 


079 


4FH 





080 


50H 


P 


081 


51H 


Q 


082 


52H 


R 


083 


53H 


S 


084 


54H 


T 


085 


55H 


U 


086 


56H 


V 


087 


57H 


W 


088 


58H 


X 


089 


59H 


Y 


090 


5AH 


Z 


091 


5BH 


r 


092 


5CH 


\ 


093 


5DH 


1 


094 


5EH 


<^ 


095 


5FH 




096 


60H 


T 



Dec 


Hex CHR 


097 


61H a 


098 


62H b 


099 


63H c 


100 


64H d 


101 


65H e 


102 


66H f 


103 


67H g 


104 


68H h 


105 


69H i 


106 


6AH : 




107 


6BH k 


108 


6CH 1 


109 


6DH in 


110 


6EH n 


111 


6FH o 


112 


70H p 


113 


71H q 


114 


72H I 




115 


73H s 


116 


74H t 


117 


75H u 


118 


76H V 


119 


77H w 


120 


78H X 


121 


79H y 


122 


7AH z 


123 


7BH 




124 


7CH 




125 


7DH 




126 


7EH 


' 


128 


7FH r 


)EL 



Dec=declmal, Hex=hexadeciinal (H) , CHR=character . 

LF=Line Feed, FF=Forin Feed, CR=Carriage Return, DEL=Rubout 



APPENDIX B 
TABLE OP MACRO ASSEMBLER DIRECTIVES 



B.I MEMORY DIRECTIVES 

ASSUME <seg-reg>:<seg-naine> [ ,<seg-reg>; 

<8eg-naTne>. . .1 
ASSUME NOTHING 
COMMENT <deliro><text><delim> 

<name> DB <exp> 

<name> DD <exp> 

<name> DQ <exp> 

<naine> DT <exp> 

<name> DW <exp> 

END (<exp>] 
<name> EQU <exp> 
<nan»e> = <exp> 

EXTRN <nanie>:<type> t ,<naine>:<type>. . .] 

PUBLIC <name> [ r<naine>. . .] 
<naroe> LABEL <type> 

NAME <module-name> 

<name> PROC [NEARl 
<name> PROC [FAR] 

I 
<proc-name> ENDP 

.RADIX <exp> 
<name> RECORD <f ield>:<width> I=<exp>] ( , . . . ] 

<name> GROUP <segment-name> [ , . . .] 

<name> SEGMENT [<align>] I<conibine>] {<class>l 

I 
<seg--name> ENDS 
EVEN 
ORG <exp> 

<name> STRUC 

I 
<struc-name> ENDS 
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B.2 MACRO DIRECTIVES 



EN DM 
EXITM 

IRP <dummy>,<parameters in angle brackets> 
I RFC <duminy>, string 
LOCAL <parameter> [ ,<parameter>. . .] 
<name> MACRO <parameter> [ ,<parameter> . . . j 
PURGE <macro-name> [,...] 
REPT <exp> 

Special Macro Operators 

& (ampersand) - concantenation 

<text> (angle brackets - single literal) 

; ; (double semicolons) - suppress comment 

! (exclamation point) - next character literal 

% (percent sign) - convert expression to number 



B.3 CONDITIONAL DIRECTIVES 

ELSE 

IF <exp> 

IFB <arg> 

IFDEF <symbol> 

IFDIF <argl>,<arg2> 

IFE <exp> 

IFIDN <argl>,<arg2> 

IFNB <arg> 

IFNDEF <symbol> 

IFl 

IF2 



B.4 LISTING DIRECTIVES 

.CREF 
.LALL 
.LFCOND 
.LIST 

%OUT <text> 
PAGE <exp> 
.SALL 
.SECOND 
SUBTTL <text> 
.TFCOND 
TITLE <text> 
.XALL 
. XCREF 
.XLIST 
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B.5 ATTRIBUTE OPERATORS 
Override operators 



Pointer (PTR) 

<attribute> PTR <expre3sion> 
Segment Override (:) (colon) 

<segnient-register> : <address->expression> 

<segfflent-naine> : <address-expression> 

<group-naine> : <address-expression> 
SHORT 

SHORT <label> 
THIS 

THIS <distance> 

THIS <type> 



Value Returning Operators 

SEG 

SEG <label> 
SEG <variable> 

OFFSET 

OFFSET <label> 
OFFSET <variable> 

TYPE 

TYPE < label > 
TYPE <variable> 

.TYPE 

.TYPE <variable> 

LENGTH 

LENGTH <variable> 

SIZE 

SIZE <variable> 



Record Specific operators 

Shift-count - (Record fieldname) 

<record-f ieldname> 
MASK 

MASK <record-f ieldname> 
WIDTH 

WIDTH <record-f ieldname> 

WIDTH <record> 
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B.€ PRECEDENCE OF OPERATORS 



All operators in a single item have the same precedence, 

regardless of the order listed within the item. Spacing and 

line breaks are used for visual clarity, not to indicate 
functional relations. 



1. LENGTH, SIZE, WIDTH, MASK 
Entries inside: parenthesis ( ) 

angle brackets < > 
square brackets [ ] 
structure variable operand: <variable> .<f ield> 

2. segment override operator: colon (:) 

3. PTR, OFFSET, SEG, TYPE, THIS 

4. HIGH, LOW 

5. *, /, MOD, SHL, SHR 

6. +, - (both unary and binary) 

7. EQ, NE, LT, LE, GT, GE 

8. Logical NOT 

9. Logical AND 

10. Logical OR, XOR 

11. SHORT,. TYPE 



APPENDIX C 
TABLE OF 8086 AND 8087 INSTROCTIONS 



Macro Assembler supports both the 8086 and 8087 mnemonics. 
The mnemonics are listed alphabetically with their full 
names. The 8086 instructions are also listed in groups 
based on the type of arguments the instruction tckkes. 



C.l 8086 INSTRUCTION MNEMONICS, ALPHABETICAL 

Mnemonic Full Name 

AAA ASCII adjust for addition 

AAD ASCII adjust for division 

AAM ASCII adjust for multiplication 

AAS ASCII adjust for subtraction 

ADC Add with carry 

ADD Add 

AND AND 

CALL CALL 

CBW Convert byte to word 

CLG Clear carry flag 

•CLD Clear direction flag 

CLI Clear interrupt flag 

CMC Complement carry flag 

CMP Compare 

CMPS Compare byte or word (of string) 

CMPSB Compare byte string 

CMPSW Compare word string 

CWD Convert word to double word 

DAA Decimal adjust for addition 

DAS Decimal adjust for subtraction 

DEC Decrement 

DIV Divide 

ESC Escape 

HLT Halt 

IDIV Integer divide 

IMUL Integer multiply 

IN Input byte or word 

INC Increment 

INT Interrupt 

INTO Interrupt on overflow 
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IRET Interrupt return 

JA Jump on above 

JAE Jump on above or equal 

JB Jump on below 

JBE Jump on below or equal 

JC Jump on carry 

JCXZ Jump on CX zero 

JE Jump on equal 

JG Jump on greater 

JGE Jump on greater or equal 

JL Jump on less than 

JLE Jump on less than or equal 

JMP Jump 

JNA Jump on not above 

JNAE Jump on not above or equal 

JNB Jump on not below 

JNBE Jump on not below or equal 

JNC Jump on no carry 

JNE Jump on not equal 

JNG Jump on not greater 

JNGE Jump on not greater or equal 

JNL Jump on not less than 

JNLE Jump on not less than or equal 

JNO Jump on not overflow 

JNP Jump on not parity 

JNS Jump on not sign 

JNZ Jump on not zero 

JO Jump on overflow 

JP Jump on parity 

JPE Jump on parity even 

JPO Jump on parity odd 

JS Jump on sign 

JZ Jump on zero 

LAHF Load AH with flags 

LDS Load pointer into DS 

LEA Load effective address 

LES Load pointer into ES 

LOCK LOCK bus 

LODS Load byte or word (of string) 

LODSB Load byte (string) 

LODSW Load word (string) 

LOOP LOOP 

LOOPE LOOP while equal 

LOOPNE LOOP while not equal 

LOOPNZ LOOP while not zero 

LOOPZ LOOP while zero 

MOV Move 

MOVS Move byte or word (of string) 

MOVBS Move byte (string) 

MOVSW Move word (string) 

MUL Multiply 

NEG Negate 

NOP No operation 

NOT NOT 

OR OR 
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OUT Output byte or word 

POP POP 

POPF POP flags 

PUSH PUSH 

PUSHF PUSH flags 

RCL Rotate through carry left 

RCR Rotate through carry right 

REP Repeat 

RET Return 

ROL Rotate left 

ROR Rotate right 

SAHF store AH into flags 

SAL Shift arithmetic left 

SAR Shift arithmetic right 

SBB Subtract with borrow 

SCAS Scan byte or word (of string) 

SCASB Scan byte (string) 

SCASW Scan word (string) 

SHL Shift left 

SHR Shift right 

STC Set carry flag 

STD Set direction flag 

STI Set interrupt flag 

STOS Store byte or word (of string) 

STOSB Store byte (string) 

STOSW Store word (string) 

SUB Subtract 

TEST TEST 

WAIT WAIT 

XCHG Exchange 

XLAT Translate 

XOR Exclusive OR 
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C.2 8087 INSTRDCTION MNEMONICS, ALPHABETICM. 



Mnemonic 

F2XM1 

F.ABS 
FADD 
FADDP 

FBLD 
FBSTP 

FCHS 

FCLEX 

FCOM 

FCOMP 

FCOMPP 

FDECSTP 

FDISI 

FDIV 

FDIVP 

FDIVR 

FDIVRP 

FENI 

FFREE • 

FIADD 

FICOM 

FICOMP 

FIDTV 

FIDIVR 

FILD 

FIMUL 

FINCSTP 

FINIT 

FIST 

FISTP 

FISUB 

FISUBR 

FLD 

FLDl 

FLDCW 

FLDENV 

FLDL2E 

FLDL2T 

FLDLG2 

FLDLN2 

FLDPI 

FLDZ 



Full Name 

Calculate 2X-1 

Take absolute value of top of stack 

Add real 

Add real and pop stack 

Load packed decimal onto top of stack 
Store packed decimal and pop stack 

Change sign on the top stack element 
Clear exceptions after WAIT 
Compare real 

Compare real and pop stack 
Compare real and pop stack twice 

Decrement stack pointer 

Disable interrupts after WAIT 

Divide real 

Divide real and Pop stack 

Reversed real divide 

Reversed real divide and pop stack twice 

Enable interrupts after WAIT 

Free stack element 

Add integer 

Integer compare 

Integer compare and pop stack 

Integer divide 

Reversed integer divide 

Load integer onto top of stack 
Integer multiply 
Increment stack pointer 
Initialize processor after WAIT 
Store integer 

Store integer and pop stack 
Integer subtract 
Reversed integer subtract 

Load real onto top of stack 
Load +1.0 onto top of stack 
Load control word 
Load 8087 environment 
Load log 2 e onto top of stack 
Load log 2 10 onto top of stack 
Load log 10 2 onto top of stack 
Load log e 2 onto top of stack 
Load pi onto top of stack 
Load +0.0 onto top of stack 
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FMUL Multiply real 

FMULP Multiply real and pop stack 

FNCLEX Clear exceptions with no WAIT 

FNDISI Disable interrupts with no WAIT 

FNENI Enable interrupts with no WAIT 

FNINIT Initialize processor, with no WAIT 

FNOP No operation 

FNSAVE Save 8087 state with no WAIT 

FNSTCW Store control word without WAIT 

FNSTENV Store 8087 environment with no WAIT 

FNSTSW Store 8087 status word with on WAIT 

FPATAN Partial arctangent function 

FPREM Partial remainder 

FPTAN Partial tangent function 

FRNDINT Round to integer 

FRSTOR Restore state 

FSAVE Save 8087 state after WAIT 

FSCALE Scale 

FSQRT Square root 

FST Store real 

PSTCW Store control word with WAIT 

FSTENV Store 8087 environment after WAIT 

FSTP Store real and pop stack 

FSTSW Store 8087 status word after WAIT 

FSUB Subtract real 

FSUBP Subtract real and pop stack 

FSUBR Reversed real subtract 

FSUBRP Reversed real subtract and pop stack 

FTST Test top of stack 

FWAIT Wait for last 8087 operation to complete 

FXAM Examine top of stack element 

FXCH Exchange contents of stack element and stack 

top 

EXTRACT Extract exponent and significand from number 

in top of stack 

FYL2X Calculate Y:log 2 X 

FYL2PI Calculate Y:log 2 (x+l) 
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C.3 8086 INSTRDCTION MNEMONICS BY ARGUMENT TYPE 



In this section, the instructions are grouped according to 
the type of argument (s) they take. In each group the 
instructions are listed alphabetically in the first column. 
The formats of the instructions with the valid argument 
types are shown in the second column. If a format shows OP, 
that format is legal for all the instructions shown in that 
group. If a format is specific to one mnemonic, the 
mnemonic is shown in the format instead of OP. 

The following abbreviations are used in these lists: 

OP = opcode; instruction mnemonic 

reg = byte register (AL,AH,BL,BH,CL,CH,DL,DK) 
or word register (AX,BX,CX,DX,SI ,DI ,BP,SP) 

r/m = register or memory address or indexed and/or based 

accum = AX or AL register 

immed = immediate 

mem = memory operand 

segreg = segment register (CS,DS,SS,ES) 

General 2 operand instructions 



Mnemonics 


Argument Types 


ADC 


OP reg, r/m 


ADD 


OP r/m, reg 


AND 


OP accum, immed 


CMP 


OP r/m, immed 


OR 




SBB 




SUB 




TEST 




XOR 





In addition, add to the arguments a sign extent for word 
immediate. 



CALL and JUMP type instructions 

Mnemonics Argument Types 

CALL OP mem InearHfar) direction 

JMP OP r/m (indirect data — 

DWORD, WORD) 
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Relative jumps 

Argument Type 

OP addr (+129 or -126 of IP at start, or 
+127 at end of jump instruction) 
Mnemonics 



JA 


JC 


JZ 


JNGE 


JNP 


JNBE 


JNAE 


JG 


JLE 


JPO 


JAE 


JBE 


JNLE 


JNG 


JNS 


JNB 


JNA 


JGE 


JNE 


JO 


JNC 


JCXZ 


JNL 


JNZ 


JP 


JB 


JE 


JL 


JNO 


JPE 
JS 


Loop 


instructions : i 


same as 


Relative jumps 



Return instruction 

Mnemonic Argument Type 

RET (immed] (optional, number of words to POP) 



No operand instructions 
Mnemonics 



AAA 
AAD 
AAM 
AAS 
CBW 
CLC 



CLD DAA 

CLI DAS 

CMC HLT 

CMPSB INTO 

CMPSW I RET 

CWD LAHF 



LODSB PUSHF STI 

LODSW SAHF STOSB 

MOVSB SCASB STOSW 

MOVSW SCASW WAIT 

NOP STC XLATB 

POPF STD 



Load instr uctio ns 

Mnemonics Argument Type 

LDS OP r/m (except that OP reg is illegal) 

LEA 

LES 



Move instructions 
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Mnemonic 



MOV 



Argument Types 

OP meniraccum 
OP accum,mem 
OP segreg,r/m 
(except CS is illegal) 
OP r/m,segreg 
OP r/m,reg 
OP reg,r/m 
OP reg,immed 
OP r/in,iinmed 



Push and pop instr uctio ns 



Mnemonics 


Argument Types 


PUSH 


OP word-reg 


POP 


OP segreg 




(POP CS is illegal) 




OP r/m 


Shift/rotate 


type instructions 


Mnemonics 


Argument Types 


RCL 


OP r/ra,l 


RCR 


OP r/m,CL 


ROL 




ROR 




SAL 




SHL 




SAR 




SHR 





Input/output instructions 
Mnemonics Argument Types 
IN 



OUT 



IN accum,byte-immed 
(immed = port 0-255) 
IN accum,OX 
OUT immed, accum 
OUT DX, accum 
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Increment/decrement instructions 

Mnemonics Argument Types 

INC OP word-reg 

DEC OP r/m 

Arith. mul t iply/di vision/negate/not 

Mnemonics Argument Type 

DIV OP r/m (implies AX OP 

IDIV r/m, except NEC) 

MUL 

IMUL 

NEC (NEG implies AX OP NOP) 

NOT 

Inte rr upt inst ruction 

Mnemonic Argument Types 

INT INT 3 (value 3 is 

one-byte instruction) 
INT byte-immed 

Exchange instruction 

Mnemonic Argument Types 

XCHG XCHG accum^reg 

XCHG reg,accum 
XCHG r eg, r/m 
XCHG r/m,reg 
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Mis cell aneou s instr uction s 

Mnemonics Argument Types 

XLAT XLAT byte-mem (only checks argument, 

not in opcode) 
ESC ESC 6-bit-number ,r/m 



String primitives 

These instructions have -bits to record only their 
operand (s), if they are byte or word, and if a segment 
override is involved. 

Mnemonics Argument Types 

CMPS CMPS byte-word, byte-word 

(CMPS right operand is ES) 
LODS LODS byte/word, byte/word 

(LODS one argument = no ES) 
MOVS MOVS byte/word, byte/word 

(MOVS left operand is ES) 
SCAS SCAS byte/word, byte/word 

(SCAS one argument » eS) 
STOS STOS byte/word, byte/word 

(STOS one argument = ES) 



Repeat prefix to string instructions 

Mnemonics 

LOCK 

REP 

REPE 

REPZ 

REPNE 

REPNZ 

C.4 8087 INSTROCTIOH MNEMONICS BY AR60MERT TYPE 



No oper 


ands 










F2XM1 


FABS 


FCHS 


FCLEX 


FCOMPP 


FDECSTP 


FDISI 


FEN I 


FINCSTP 


FINIT 


FLDl 


FLD2E 


FLD2T 


FLDLG2 


FLDLN2 


FLDPI 


FLDZ 


FNCLEX 


FNDISI 


FNENI 


FNINIT 


FNOP 


FPATAN 


FPREM 


FPTAN 


FRNDINT 


PSCALE 


PSQRT 


FTST 


FXAM 



FXTRACT FYL2X FYL2XP1 FWAIT 
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2-Arqumen t Float ing Ari th matic 



Mnemonics 


Argument Types 


FADD 


Blank 


PDIV 


mem 4,8 bytes 


FDIVR 


ST,ST(i) 


FMUL 


ST(i) ,ST 


FSUB 




FSUBR 




Stack only 


floating point arithmatic 


Mnemonics 


Argument Types 


FADDP 


ST(i) 


FDIVP 


ST 


FDIVRP 




FMULP 




FSUBP 




FSUBRP 




Compare and store using stack 


Mnemonics 


Argument Types 


FCOM 


ST 


FCOMP 


ST(i) 


FST 


blank 


Stack 




Mnemonics 


Argument Types 


FFREE 


ST(i) 


FXCH 


blank 


Integer arithmatic 


Mnemonics 


Argument Types 


FIADD 


mem 2,4 bytes 


FICOM 




FICOMP 




FIDIV 




FIDIVR 




FIMUL 




FIST 




FISUB 




FISUBR 
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Floating goint load/store memory 
Mnemonics Argument Types 

FLD mem 4,8, or 10 bytes 

FSTP 

Integer load/store memory 

Mnemonics Argument Types 

FILD mem 2,4, or 8 bytes 

FIST? 

Load/store control or status 
Mnemonics Argument Types 

FLDCW mem 2 bytes 

FNSTCW 

FNSTSW 

FSTCW 

FSTSW 

Sav e/Re store 8i087 env ir onment 

Mnemonics Argument Types 

FLDENV mem 14 bytes 

FNSTENV 

FSTENV 

9^^_rJyi_t.e memory (8087 Sav e/Restor e ent ire state) 

Mnemonics Argument Types 

FNSAVE mem 94 bytes 

FRSTOR 

FSAVE 

BCD load/store 

Mnemonics Argument Types 

FBLD mem 10 bytes 

FBSTP 
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CHAPTER 1 
INTRODUCTION 



The Microsoft Linker Utility (MS-LINK) is a relocatable 
linker designed to link separately produced modules of 8086 
object code. The input to MS-LINK is a subset of the Intel 
object module format standard. 

MS-LINK prompts you for all MS-LINK commands. Your answers 
to these prompts are the commands for MS-LINK. 

The output file from MS-LINK (a Run file) is not bound to 
specific memory addresses and, therefore, can be loaded and 
executed at any convenient address by the operating system. 

MS-LINK uses a dictionary-indexed library search method, 
which substantially reduces link time for sessions involving 
library searches. 

MS-LINK is able to link files totaling 1 megabyte. 

NOTE 

This manual describes some of 
the technical information 
about MS-LINK. It is 
recommended that this manual 
be read in conjunction with 
Chapter 9, "The Linker Program 
(MS-LINK)," in the MS-DOS 
User's Guide. 
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1.1 OVERVIEW OF MS-LINK OPERATIOH 

MS-LINK performs the following steps to combine object 
modules and produce a Run file: 

1. Reads segments in object modules 

2. Assigns addresses to segments 

3. Assigns public symbol addresses 

4. Reads data in segments 

5. Reads all relocation references in object modules 

6. Resolves references and determines relocation 
information 

7. Outputs a Run file (executable image) and 
relocation information 

As it combines modules, MS-LINK can search multiple library 
files for definitions of any external references left 
unresolved. 

MS-LINK also produces a List file that shows external 
references resolved and any error messages. 

MS-LINK uses available memory as much as possible. When 
available memory is exhausted, MS-LINK then creates a disk 
file (VM.TMP) to use as temporary memory. 
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The following figure illustrates the MS-LINK operation. 



object 
module 



object 
module 



object 
module 



HI 



Microsoft 
Linker Utility 



I 



Executable Image 



Relocation Information 



Figure 1. MS-LINK Operation 



The executable image contains 



the concatenated object 
The relocation i nforma tion 
when 



modules that make the Run file. 

is a list of long addresses that must change when the 
executable image is relocated in memory. Refer to Section 
1.7.4, "Long References," for an explanation of long 
addresses. 
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1 . 2 DEFINITIONS 

The following terms describe the functioning of MS-LINK. An 
understanding of the concepts that define these terms will 
provide a basic understanding of the way MS-LINK works. 
Refer to the MS-DOS User' s Guide for more information on 
these definitions. 

1. Segment 

A segment is a contiguous area of memory up to 
64K bytes in length. A segment may be located 
anywhere in 8086 memory. The contents of a 
segment are addressed by a canonical frame 
address and offset within that frame. Refer to 
Section 1.5, "Segment Addresses," for further 
discussion of canonical frames. 



2. Group 

A group is a collection of segments that fit 
within 64K bytes of memory. The segments are 
named to the group by the assembler, by the 
compiler, or by you. You give the group name 
in the assembly language program. For the 
high-level languages (BASIC, FORTRAN, COBOL, 
Pascal), the naming is carried out by the 
compiler. 

The group is used for addressing segments in 
memory. Each group is addressed by a common 
canonical frame. This frame is the lowest 
canonical frame of the segments that belong to 
the group. It is a usual practice in assembler 
and higher languages for the canonical frame 
address to be contained in a segment register. 
MS-LINK checks to see that the object modules 
of a group meet the 64K-byte constraint. 



3. Class 



A class is a collection of segments. The 
naming of segments to a class controls the 
order and relative placement of segments in 
memory. You give the class name in the 
assembly language program. For the high-level 
languages (BASIC, FORTRAN, COBOL, Pascal), the 
naming is carried out by the compiler. The 
segments are named to a class at compile time 
or assembly time. 

The segments of a class are loaded into memory 
contiguously. The segments are ordered within 
a class in the order the Linker encounters the 
segments in the object files. One class 
precedes another in memory only if a segment 
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for the first class precedes all segments for 
the second class in the input to MS-LINK. 
Classes may be loaded across 64K-byte 
boundaries. Groups may span classes. 



4 . Alignment 

Alignment refers to certain segment boundaries. 
These can be byte, word, or paragraph 
boundaries. 

Byt e Alignment ; A segment can begin on any 
byte boundary. 

Word Alignment ; The beginning address of a 
segment must occur on an even address. 

Paragraph Alignmen t; The beginning address 
of a segment must occur on a segment 
(16-byte) boundary. 



5 . Combine Typ e 

A combine type is an attribute of a segment; 
it tells the Linker how to combine segments of 
a like name or it relays other information 
about the properties of a segment. Combine 
types are: stack, public, private, and common. 
The way MS-LINK arranges these combine types is 
discussed in the next section. 



CHAPTER 2 
MS-LINK TECHNICAL INFORMATION 



2.1 BOW MS-LINK COMBINES AND ARRANGES SEGMENTS 

MS-LINK works with four combine types, which are declared in 
the source module for the assembler or compiler: private, 
public, stack, and common. The memory combine type 
available in Microsoft's Macro Assembler is processed the 
same as public combine type. MS-LINK does not automatically 
place memory combine type as the highest segments (as 
defined in the Intel standard) . 

MS-LINK arranges these combine types as follows: 



Private 



ED 



Private segments are loaded separately 
and remain separate. They may be 
physically (but not logically) con- 
tiguous even if the segments have the 
same name. Each private segment has 
its own canonical frame. 



Public and Stack 
^0 







-A- 



Public and stack segments of the 
same name and class name are loaded 
contiguously. Offset is from the 
beginning of the first segment loaded 
through the last segment loaded. 
There is only one canonical frame for 
all public segments of the same name 
and class name. Stack and memory com- 
bine types are treated the same as 
public. However, the Stack Pointer 
is set to the last address of the 
first stack segment. 
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Common 



A* 



Common segments of the same name and 
class name are loaded overlapping one 
another. There is only one canonical 
frame for all common segments of the 
same name. The length of the common 
area is the length of the longest 
segment. 



Placing segments in a group in the assembler provides offset 
addressing of items from a single canonical frame for all 
segments in that group. 



DS:DGROUP >XXXXOH. — relative offset 



Any number of 
other segments 
may intervene 
between segments 
of a group. Thus, 
the offset of POO 
may be greater than 
the size of segments 
in the group combined, 
but no larger than 64K. 




An operand of 
DGROUPtFOO in assembly 
language returns the 
offset of POO from the 
beginning of the first 
segment (segment A 
here) . 



Segments are partitioned by declared class names. The 
Linker loads all the segments belonging to the first class 
name encountered, then loads all the segments of the next 
class name encountered, and so on until all classes have 
been loaded. 



If your program contains: 

A SEGMENT 'POO' 

B SEGMENT 'BAZ* 

C SEGMENT 'BAZ' 

D SEGMENT 'ZOO' 

E SEGMENT 'FOG' 



They will be loaded as: 

'POO' 

A 

E 
•BAZ' 

B 

C 
•ZOO* 

D 
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If you are writing assembly language programs, you can 
control the order of classes in memory by writing a dummy 
module and listing it first after the MS-LINK Object 
Modules; prompt. The dummy module declares segments into 
classes in the order you want the classes loaded. 



WARNING 

Do not use this method with 

BASIC, COBOL, FORTRAN, or 

Pascal programs. Allow the 

compiler and the Linker to 

perform their tasks in the 
normal way. 



Example; 



A 


SEGMENT 


•CODE' 


A 


ENDS 




B 


SEGMENT 


•CONST' 


B 


ENDS 




C 


SEGMENT 


'DATA' 


C 


ENDS 




D 


SEGMENT 


STACK • STACK ' 


D 


ENDS 




E 


SEGMENT 


'MEMORY' 


E 


ENDS 





Make sure you declare all classes to be used in your program 
in this module. If you do not, you lose absolute control 
over the ordering of classes. 

Also, if you want memory combine type to be loaded as the 
last segments of your program, you can use this method. 
Simply add MEMORY between SEGMENT and 'MEMORY' in the E 
segment line above. Note, however, that these segments are 
loaded last only because you imposed this control on them, 
not because of any inherent capability in the Linker or 
assembler operations. 
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2.2 SEGMENT ADDRESSES 

The 8086 must be able to address all segments in memory. 
Any 20-bit number can be addressed. The 8086 represents 
these numbers as two 16-bit numbers; for example, HEX F:12. 
The F represents a canonical frame address and the 12 is the 
offset. The canonical frame address is the largest frame 
address or segment address that can contain the segment. An 
offset is the segment's location, offset from the beginning 
of the canonical frame. 

The Linker recognizes a segment by its canonical frame 
address and its offset within the frame. 

To convert the segmented address P:12 to a 20-bit number, 
shift the frame address left 4 bits, and add the offset. 
Using the above example: 

FO 
+ 12 



F:12 = 102 (20-bit address) 

2.3 HOW MS-LINK ASSIGNS ADDRESSES 

To assign addresses to segments, MS-LINK: 



Orders each segment by segment and class name. 

On the basis of the alignment and size of each 
segment (assuming they are contiguous) , the Linker 
assigns a frame address and an offset to each 
segment. This information is used for resolving 
relocatable references. The addresses start at 
0:0. 
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2.4 RELOCATION FIXUPS 

MS-LINK performs relocation fixups (i.e., resolves) on four 
types of references in object modules: 

Short 

Near Self-Relative 

Near Segment-Relative 

Long 

These references and the Linker's fixups are described in 
the next sections. 



2.4.1 Short References 

Short references are all self-relative. The implication is 
that the frame address of the target and source frames are 
the same. MS-LINK will generate the fixup error message 

Fixup offset exceeds field width 

under the following conditions: 



1. The target and source frame addresses are 
different. 

2. The target is more than 128 bytes before or after 
the source frame address. 



The resulting value of the short reference must fit into one 
signed byte. 



2.4.2 Near Self-Relative References 

When near self-relative references are used, the frame 

address of the target and source frames are the same. 

MS-LINK will generate the fixup error message under the 
following conditions: 



1. The target and source frame addresses are 
different. 
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2. The target is more than 32K before or after the 
source frame address. 



The resulting value of the near self-relative reference must 
fit into one signed word (16 bits) . 



2.4.3 Hear Segaent-Relative References 

Given the target's canonical frame r another frame is 
specified (via an ASSUME directive or the : operator in 
assembly language; or via a high-level language 
convention) . The target must be addressable through the 
canonical frame specified. MS-LINK will generate the fixup 
error message under the following conditions: 

1. The offset of the target within the specified frame 
is greater than 64K or less than zero. 

2. The beginning of the canonical frame of the target 
is not addressable by the specified frame. 

The resulting value of a near segment-relative reference 
must be an unsigned 16-bit quantity. 



2.4.4 Long References 

Long references have a target and another frame (specified 
by an ASSUME or by a high-level language) . The target must 
be addressable through the canonical frame specified. 
MS-LINK will generate the fixup error message under the 
following conditions: 

1. The offset of the target within the specified frame 
is greater than 64K or less than zero. 

2. The beginning of the canonical frame of the target 
is not addressable by the specified frame. 

The resulting value of a long reference must be a frame 
address and an offset. 
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2.5 SAMPLE MS-LINK SESSION 

The following example illustrates the type of information 
that is displayed during an MS-LINK session. 

In response to the MS-DOS prompt (>) , the system responds 
with the following messages and prompts. Answers to the 
prompts are underlined. Note that pathnames are supported 
under MS-DOS 2.0. Therefore, your answer js to MS-LINK 
prompts can be full pathnames instead of filenames. 

Microsoft Object Linker V.2.00 

(C) Copyright 1982 by Microsoft Inc. 

Object Modules (.OBJ]: 10 SYSINIT 
Run File (I0.EXE1 : 
List File (NUL.MAPl: 10 /MAP 
Libraries [.LIB]: }_ 



Notes: 

1. By specifying /MAP , you can get both a sorted 
alphabetic listing and a sorted address listing of 
public symbols. 

2. By responding PRN to the List File: prompt, you 
can redirect your output to the printer. 

3. By specifying the /LINE switch, MS-LINK gives you a 
listing of all line numbers for all modules. (Note 
that the /LINE switch can generate a large volume 
of output.) 

4. By pressing <RETURN> in response to the Libraries: 
prompt, an automatic library search is performed. 

Once MS-LINK locates all libraries, the linker map displays 
a list of segments in the order of their appearance within 
the load module. The list might look like this: 

Start Stop Length Name 
OOOOOH 009ECH 09EDH CODE 
009F0H 01166H 0777H SYSINITSEG 

The information in the Start and Stop columns shows the 
20-bit hex address of each segment relative to location 
zero. Location zero is the beginning of the load module. 
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Because the /MAP switch was used, MS-LINK displays the 
public symbols by name and value. For example: 



ADDRESS 

009F:0012 

009F:0005 

009F:0011 

009F:000B 

009F:0013 

009F:0009 

O09F:000F 

009F:0000 



PUBLICS BY NAME 

BUFFERS 

CURRENT_DOS_LOCAT ION 

DEFAULT_DRIVE 

DEVICE_LIST 

FILES 

FINAL_DOS_LOCATION 

MEMORY_SIZE 

SYSINIT 



ADDRESS 

009F:0000 

009F:0005 

009F:0009 

009F:000B 

009F:000F 

009F:0011 

009F:0012 

009F:0013 



PUBLICS BY VALUE 

SYSINIT 

CURRENT_DOS_LOCAT I ON 

FINAL_DOS_LOCAT ION 

DEVICE_LIST 

MEMORY_SIZE 

DEFAULT_DRIVE 

BUFFERS 

FILES 



The addresses of the public symbols are in the frame:offset 

format, showing the location relative to zero as the 

beginning of the load module. In some cases, an entry may 
look like this: 



780:A2 

This entry appears to be the address of a load module that 
is almost one megabyte in size. Actually, the area being 
referenced is relative to a segment base that is pointing to 
a segment below the relative zero beginning of the load 
module. This condition produces a pointer that has 
effectively gone negative. 

When MS-LINK has completed processing, the following message 
is displayed: 



Program entry point at 0009F:0000 



MS-LINK TECHNICAL INFORMATION Page 2-9 

2.6 ERROR MESSAGES 

All messages, except for the warning messages, cause the 
MS-LINK session to end. After you locate and correct a 
problem, you must rerun MS-LINK, 

Messages appear in the List file and are displayed on the 
screen. If you direct the List file to CON, the error 
messages will not be displayed on the screen. 

MS-LINK error messages are described in Chapter 9 of the 
MS-DOS User's Guide. 



ADDENDUM to the Microsoft MS-DOS 
Macro Assembler Manual 

MS-LINK 



NOTE 

References in the Macro 
Assembler Manual to the MS-DOS 
User' s Guide refer to this 
addendum. You may want to 
place thi's addendum before the 
MS-LINK section in this 
manual. 
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1.0 DEFINITIONS 

Some of the terms used in the MS-LINK section of this manual 
are explained below to help you understand how MS-LINK 
works. Generally, if you are linking object modules 
compiled from BASIC, Pascal, or a high-level language, you 
will not need to know these terms. If you are writing and 
compiling programs in assembly language, however, you will 
need to understand MS-LINK and the definitions described 
below. 

In MS-DOS, memory can be divided into segments, classes, and 
groups. Figure 1 illustrates these concepts. 



Memory 




shaded area = a group (64K bytes addressable) 
Figure 1. How Memory Is Divided 
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Example: 



Segment Name 



Segment Class 
Name 



Segment 1 
Segment 2 
Segment 12 



PROG.l 
PROG . 2 
PRCX3.3 



CODE 
CODE 
DATA 



Note that segments 1, 2, and 12 have different segment names 

but may or may not have the same segment class name. 

Segments 1, 2, and 12 form a group , with a group address of 

the lowest address of segment 1 (i.e., the lowest address in 
memory) . 

Each segment has a segment name and a class name . MS-LINK 
loads all segments into memory by class name, from the first 
segment encountered to the last. All segments assigned to 
the same class are loaded into memory contiguously. 

During processing, MS-LINK references segments by their 
addresses in memory (where they are located) . MS-LINK does 
this by finding groups of segments. 

A group is a collection of segments that fit within a 64K 

byte area of memory. The segments do not need to be 

contiguous to form a group (see Figure 1). The address of 

any group is the lowest address of the segments in that 

group. At link time, MS-LINK analyzes the groups, then 

references the segments by the address in memory of that 
group. A program may consist of one or more groups. 

If you are writing in assembly language, you may assign the 
group and class names in your program. In high-level 
languages (BASIC, COBOL, FORTRAN, Pascal), the naming is 
done automatically by the compiler. 
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2.0 PILES THAT MS-LINK USES 

MS-LINK performs the following functions: 

Works with one or more input files 

Produces two output files 

May create a temporary disk file 

May be directed to search up to eight library files 

For each type of file, you can give a three-part file 
specification. The format of MS-LINK file specifications is 
the same as that of a disk file: 

fd: ] <f ilename> l< .ext>l 

where: d^ is the drive designation. Permissible drive 
designations for MS-LINK are A: through 0: . The 
colon is always required as part of the drive 
designation. 

filename is any legal filename of one to eight 
characters. 

■ext is a one- to three-character extension to the 
filename. The period is always required as part of 
the extension. 



2.1 Input Pile Extensions 

If no filename extensions are given in the input (object) 
file specifications, MS-LINK will recognize the following 
extensions by default: 

.OBJ Object 
•LIB Library 



2.2 Output File Extensions 

MS-LINK appends the following default extensions to the 
output (run and list) files: 

.EXE Run (may not be overridden) 
.MAP List (may be overridden) 



Page 3-5 



2.3 VM.TMP (Temporary) File 



MS-LINK uses available memory for the link session. If the 
files to be linked create an output file that exceeds 
available memory, MS-LINK will create a temporary file, name 
it VM.TMP, and put it on the disk in the default drive. If 
MS-LINK creates VM.TMP, it will display the message: 

VM.TMP has been created. 

Do not change diskette in drive, <d:> 

Once this message has been displayed, you must not remove 
the disk from the default drive until the link session ends. 
If the disk is removed, the operation of MS-LINK will be 
unpredictable, and MS-LINK might display the error message: 

Unexpected end of file on VM.TMP 

The contents of VM.TMP are written to the file named 
following the Run File: prompt. VM.TMP is a working file 
only and is deleted at the end of the linking session. 



WARNING 

Do not use VM.TMP as a 
filename for any file. If you 
have a file named VM.TMP on 
the default drive and MS-LINK 
needs to create a VM.TMP file, 
MS-LINK will delete the VM.TMP 
already on disk and create a 
new VM.TMP. Thus, the 
contents of the previous 
VM.TMP file will be lost. 
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3.0 HOW TO START MS-LINK 



MS-LINK requires two types of input: a command to start 
MS-LINK and responses to command prompts. In addition, 
sevfen switches control MS-LINK features. Usually, you will 
type all the commands to MS-LINK on the terminal keyboard. 
As an option, answers to the command prompts and any 
switches may be contained in a response file. Command 
characters can be used to assist you while giving commands 
to MS-LINK. 

MS-LINK can be started in any of three ways. The first 
method is to type the commands in response to individual 
prompts. In the second method, you type all commands and 
switches on the line used to start MS-LINK. To start 
MS-LINK by the third method, you must create a response file 
that contains all the necessary commands, and then tell 
MS-LINK where that file is when you start MS-LINK. 



Summary of Methods to Start MS-LINK 

Method 1 LINK 

Method 2 LINK <f ilenames> (/switchesl 

Method 3 LINK §<filespec> 
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3.1 Method 1: Proapts 

To Start MS-LINK with Method 1, type: 

LINK 

MS-LINK will be loaded into memory. MS-LINK will then 
display four text prompts that appear one at a time. You 
answer the prompts to command MS-LINK to perform specific 
tasks. 

At the end of each line, you may type one or more switches, 
preceded by the switch character, a forward slash (/) . 

The command prompts are summarized below. 



PROMPT 

Object Modules f.OBJ] 



Run File \ .EXE] 



List File [NUL.MAPl 



Libraries ( .LIB] : 



RESPONSES 

List .OBJ files to be 
linked. They must be 
separated by blank spaces 
or plus signs (+) . If a 
plus sign is the last 
character typed, the 
prompt will reappear. 
There is no default; a 
response is required. 

Give filename for 
executable object code. 
The default is 
first-object-filename.EXE. 
(You cannot change the 
output extension.) 

Give filename for listing. 
The default is NUL.MAP. 

List filenames to be 
searched, separated by 
blank spaces or plus signs 

{+) . If a plus sign is 
the last character typed, 
the prompt will reappear. 
The default is to search 
for default libraries in 
the object modules. 

(Extensions will be 
changed to .LIB.) 
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3.2 Method 2; Conaand Line 



To Start MS-LINK using Method 2, type all commands on one 
line. The entries following LINK are responses to the 
command prompts. The entry fields for the different prompts 
must be separ.ated by commas; Use the following syntax: 

LINK <object-list>,<runf ile>,<listfile>,<lib-list> [/switch] 



where: object-list is a list of object modules, 
separated by plus signs. 

runf ile is the name of the file that receives 
the executable output. 

listf ile is the name of the file that receives 
the listing. 

lib-list is a list of library modules to be 
searched. 

/switch refers to optional switches, which may 
be placed following any of the response entries 
(just before any of the commas or after the 
<lib-list>, as shown). 

To select the default for a field, simply type a second 
comma with no spaces between the two commas. 

Example: 

LINK 

FUN+TEXT+TABLE+CARE/P/M , , FUNLI ST ,COBLIB . LIB 

This command causes MS-LINK to be loaded; then the object 
modules FUN. OB J, TEXT. OB J, TABLE. OB J, and CARE. OB J are 
loaded. MS-LINK then pauses (as a result of using the /P 
switch) . MS-LINK links the object modules when you press 
any key, and produces a global symbol map (the /M switch) . 
MS-LINK then defaults to the FUN. EXE run file; creates a 
list file named FUNLIST.MAP; and searches the library file 
COBLIB.LIB. 
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3.3 Method 3: Response Pile 

To start MS-LINK with Method 3, type: 

LINK e<filespec> 

where; f ilespec is the name of a response file. A response 
file contains answers to the MS-LINK prompts (shown 
in Method 1) and may also contain any of the 
switches. When naming a response file, use of the 
filename extension is optional. Method 3 permits 
the command that starts MS-LINK to be entered from 
the keyboard or within a batch file, without 
requiring you to make any further responses. 

To use this option, you must create a response file 
containing several lines of text, each of which is the 
response to an MS-LINK prompt. The responses must be in the 
same order as the MS-LINK prompts discussed in Method 1. If 
desired, a long response to the Object Modules; or 
Libraries: prompt may be typed on several lines by using a 
plus sign (-I-) to continue the same response onto the next 
line. 

Switches and command characters can be used in the response 
file the same way as they are used for responses typed on 
the terminal keyboard. 

When the MS-LINK session begins, each prompt will be 
displayed in order with the responses from the response 
file. If the response file does not contain answers for all 
the prompts (in the form of filenames, the semicolon command 
character, or carriage returns), MS-LINK will display the 
prompt which does not have a response, then wait for you to 
type a legal response. When a legal response has been 
typed, MS-LINK continues the link session. 



Example: 
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FUN TEXT TABLE CARE 
/PAUSE/MAP 
FUNLIST 
COBLIB.LIB 



This response file tells MS-LINK to load the four object 
modules named FUN, TEXT, TABLE, and CARE. MS-LINK pauses to 
permit you to swap disks before producing a public symbol 
map (see discussion under /PAUSE in the "Switches" section 
before using this feature) . When you press any key, the 
output files will be named FUN. EXE and FUNLIST. MAP. MS-LINK 
will then search the library file COBLIB.LIB, and will use 
default settings for the switches. 
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4.0 COMMAND CHARACTERS 

MS-LINK recognizes three command characters. 

Plus sign Use the plus sign (+) to separate 
entries and to extend the current line 
in response to the Object Modules: and 
Libraries: prompts. (A blank space 
may be used to separate object 
modules.) To type a large number of 
responses (each may be very long) , type 
a plus sign/<RETURN> at the end of the 
line to extend it. If the plus 
sign/<RETURN> is the last entry 
following these two prompts, MS-LINK 
will prompt you for more module names. 
When the Object Modules: or Libraries: 
prompt appears again, continue to type 
responses. When all the modules to be 
linked and libraries to be searched 
have been listed, be sure the response 
line ends with a module name and a 
<RETURN> and not a plus sign/<RETURN> . 

Example: 

Object Modules [.OBJ]: FUN TEXT TABLE 

CARE+<RETURN> 

Object Modules [.OBJ]: 

FOO+FLI PFLOP+ JUNQUE+ < RETURN > 

Object Modules (.OBJl: CORSAIR< RETURN > 
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Semicolon To select default responses to the 

remaining prompts r use a single semicolon 

(;) followed immediately by a carriage 
return at any time after the first prompt 

(Run File:). This feature saves time and 

overrides the need to press a series of 
< RETURN > keys. 



NOTE 

Once the semicolon has been entered 
(by pressing the <RETURN> key) , you 
can no longer respond to any of the 
prompts for that link session. 
Therefore, do not use the semicolon 
to skip some prompts. To skip 
prompts, use the <RETURN> key. 



Example: 

Object Modules t.OBJl: FUN TEXT TABLE 

CARE<RETURN> 

Run Module [FUN. EXE]: ;<RETURN> 

No other prompts will appear, and MS-LINK 
will use the default values (including 
FUN. MAP for the list file). 



<CONTROL-C> Use the <CONTROL-C> key to abort the link 
session at any time. If you type an 
erroneous response, such as the wrong 
filename or an incorrectly spelled 
filename, you must press <CONTROL-C> to 
exit MS-LINK, then you must restart 
MS-LINK. If the error has been typed but 
you have not pressed the <RETURN> key, you 
may delete the erroneous characters with 
the backspace key, but for that line only. 
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5.0 MS-LINK SWITCHES 



The seven MS-LINK switches control various MS-LINK 
functions. Switches must be typed at the end of a prompt 
response, regardless of which method is used to start 
MS-LINK. Switches may be grouped at the end of any 
response, or may be scattered at the end of several. If 
more than one switch is typed at the end of a response, each 
switch must be preceded by a forward slash (/) . 

All switches may be abbreviated. The only restriction is 

that an abbreviation must be sequential from the first 

letter through the last typed; no gaps or transpositions 
are allowed. For example: 

Legal Illegal 

/D /DSL 

/DS /DAL 

/DSA /DLC 

/DSALLOCA /DSALLOCT 



/DSALLOGATE 

Using the /DSALLOCATE switch tells MS-LINK to 
load all data at the high end of the Data 
Segment. Otherwise, MS-LINK loads all data at 
the low end of the Data Segment. At runtime, 
the DS pointer is set to the lowest possible 
address to allow the entire DS segment to be 
used. Use of the /DSALLOCATE switch in 
combination with the default load low (that 
is, the /HIGH switch is not used) permits the 
user application to dynamically allocate any 
available memory below the area specifically 
allocated within DGroup, yet to remain 
addressable by the same DS pointer. This 
dynamic allocation is needed for Pascal and 
FORTRAN programs. 



NOTE 

Your application program may 
dynamically allocate up to 64K bytes 
(or the actual amount of memory 
available) less the amount allocated 
within DGroup. 
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/HIGH 



Use of the /HIGH switch causes MS-LINK to 
place the run file as high as possible in 
memory. Otherwise, MS-LINK places the run 
file as low as possible. 



IMPORTANT 

Do not use the /HIGH switch with 
Pascal or FORTRAN programs. 



/LINENUMBERS 

The /LINENUMBERS switch tells MS-LINK to 
include in the list file the line numbers and 
addresses of the source statements in the 
input modules. Otherwise, line numbers are 
not included in the list file. 



NOTE 

Some compilers produce object modules 
that do not contain line number 
information. In these cases, of 
course, MS-LINK cannot include line 
numbers. 



/MAP 



/MAP directs MS-LINK to list all public 
(global) symbols defined in the input modules. 
If /MAP is not given, MS-LINK will list only 
errors (including undefined globals) . 

The symbols are listed alphabetically at the 
end of the list file. For each symbol, 
MS-LINK lists its value and its segmentrof fset 
location in the run file. 
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/PAUSE 

The /PAUSE switch causes MS-LINK to pause in the 
link session when the switch is encountered. 
Normally, MS-LINK performs the linking session from 
beginning to end without stopping. This switch 
allows the user to swap disks before MS-LINK 
outputs the run (.EXE) file. 

When MS-LINK encounters the /PAUSE switch, it 
displays the message: 

About to generate .EXE file 
Change disks <hit any key> 



MS-LINK resumes processing when you press any key. 



CAUTION 

Do not remove the disk which 
will receive the list file, or 
the disk used for the VM.TMP 
file, if one has been created. 



/STACK :<number> 

number represents any positive numeric value (in 
hexadecimal radix) up to 65536 bytes. If a value 
from 1 to 511 is typed, MS-LINK will use 512. If 
the /STACK switch is not used for a link session, 
MS-LINK will calculate the necessary stack size 
automatically. 

All compilers and assemblers should provide 
information in the object modules that allow the 
linker to compute the required stack size. 

At least one object (input) module must contain a 
stack allocation statement. If not, MS-LINK will 
display the following error message: 

WARNING: NO STACK STATEMENT 



/NO 
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/NO is short for NODEFAULTLIBRARYSEARCH . This 
switch tells MS-LINK to not search the default 
(product) libraries in the object modules. For 
example, if you are linking object modules in 
Pascal, specifying the /NO switch tells MS-LINK to 
not automatically search the library named 
PASCAL. LIB to resolve external references. 
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6.0 ERROR MESSAGES 



All errors cause the link session to abort. After the cause 
has been found and corrected, MS-LINK must be rerun. The 
following error messages are displayed by MS-LINK: 

ATTEMPT TO ACCESS DATA OUTSIDE OF SEGMENT BOUNDS, POSSIBLY 
BAD OBJECT MODULE 

There is probably a bad object file. 

BAD NUMERIC PARAMETER 

Numeric value is not in digits. 



CANNOT OPEN TEMPORARY FILE 

MS-LINK is unable to create the file VM.TMP because 
the disk directory is full. Insert a new disk. Do 
not remove the disk that will receive the List. MAP 
file. 



ERROR: DUP RECORD TOO COMPLEX 

The DUP record in the assembly language module is 
too complex. Simplify the DUP record in your 
assembly language program. 



ERROR: FIXUP OFFSET EXCEEDS FIELD WIDTH 

An assembly language instruction refers to an 
address with a short instruction instead of a long 
instruction. Edit your assembly language source 
and reassemble. 



INPUT FILE READ ERROR 

There is probably a bad object file. 

INVALID OBJECT MODULE 

An object module (s) is incorrectly formed or 
incomplete (as when assembly is stopped in the 
middle) . 



SYMBOL DEFINED MORE THAN ONCE 

MS-LINK found two or more modules that define a 
single symbol name. 



PROGRAM SIZE OR NUMBER OF SEGMENTS EXCEEDS CAPACITY OF 

LINKER 

The total size may not exceed 384K bytes, and the 
number of segments may not exceed 255. 
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REQUESTED STACK SIZE EXCEEDS 64K 

Specify a size greater than or equal to 64K bytes 
with the /STACK switch. 

SEGMENT SIZE EXCEEDS 64K 

64K bytes is the addressing system limit. 



SYMBOL TABLE CAPACITY EXCEEDED 

Very many and/or very long names were typed, 
exceeding the limit of approximately 25K bytes. 



TCX) MANY EXTERNAL SYMBOLS IN ONE MODULE 

The limit is 256 external symbols per module. 



TOO MANY GROUPS 

The limit is 10 groups, 



TOO MANY LIBRARIES SPECIFIED 

The limit is 8 libraries. 



TOO MANY PUBLIC SYMBOLS 

The limit is 1024 public symbols. 



TOO MANY SEGMENTS OR CLASSES 

The limit is 256 (segments and classes taken 
together) . 



UNRESOLVED EXTERNALS: <list> 

The external symbols listed have no defining module 
among the modules or library files specified. 



VM READ ERROR 

This is a disk error; it is not caused by MS-LINK. 



WARNING: NO STACK SEGMENT 

None of the object modules specified contains a 
statement allocating stack space, although the 
/STACK switch was specified. 



WARNING: SEGMENT OF ABSOLUTE OR UNKNOWN TYPE 

There is a bad object module, or an attempt has 
been made to link modules that MS-LINK cannot 
handle (e.g., an absolute object module). 
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WRITE ERROR IN TMP FILE 

No more disk space remains to expand the VM.TMP 
file. 



WRITE ERROR ON RUN FILE 

Usually, there is not enough disk space for the run 
file. 
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CHAPTER 1 
IHTRODaCTION 



1.1 FEATURES OF MS-LIB 

Microsoft LIB is a library manager. With MS-LIB, you can: 

Create and modify library files that are used with 
Microsoft's MS-LINK linker utility 

Add object files to a library 

Delete modules from a library 

Extract modules from a library and place the 
extracted modules into separate object files 

MS-LIB can create either general or special libraries, for a 
variety of programs or for specific programs. With MS-LIB 
you can create a library, or you can create a library for 
one program only. The result is fast linking and more 
efficient execution for a language compiler or for one 
program. 

You can modify individual modules within a library by 
extracting the modules, making changes, then adding the 
modules to the library again. You can also replace an 
existing module with a different module or with a new 
version of an existing module. 

The command scanner in MS-LIB is also used in Microsoft 
MS-LINK, MS-Pascal, MS-FORTRAN, and other 16-bit Microsoft 
products. If you have used any of these products, using 
MS-LIB should be familiar to you. Command syntax is 
straightforward, and MS-LIB prompts you for commands that 
you have not supplied. 
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1.2 OVERVIEW OP MS-LIB OPERATION 

MS-LIB performs five library manager functions: 

Deletes modules 

Extracts a module and places it in a separate 
object file 

Appends an object file as a module of a library 

Replaces a module in the library file with a new 
module 

Creates a library file 

During each library session, MS-LIB deletes or extracts 
modules, then appends new ones to the library file. MS-LIB 
reads each module into memory, checks it for consistency, 
and writes it back to the file. If you delete a module, 
MS-LIB reads that module into memory but does not write it 
back to the file. When MS-LIB writes back the next module 
to be retained, it places that module at the end of the last 
module written. This procedure effectively "closes up" the 
disk space to keep the library file from growing too large. 

When MS-LIB has read the library file, it appends any new 
modules to the end of the file. Finally, MS-LIB creates the 
index, which MS-LINK uses to find modules and symbols in the 
library file. MS-LIB will output a cross-reference listing 
of the PUBLIC symbols in the library, if you request such a 
listing. 

Example: 

LIBX PASCAL+HEAP-HEAP; 

This command first deletes the library module HEAP from the 
library file, then adds the file HEAP. OBJ as the last module 
in the library. Note that the replace function is simply 
the delete-append functions in succession. Also note that 
you can specify delete, append, or extract functions in any 
order. This order of execution prevents confusion in MS-LIB 
when a new version of a module replaces a version in the 
library file. 

The following figure illustrates the MS-LIB operation. 
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Figure I. MS-LIB Operation 



CHAPTER 2 
RUNNING MS-LIB 



Running MS-LIB requires two types of commands: a command to 
start MS-LIB and answers to command prompts. Usually you 
will type all the commands to MS-LIB on a command line or in 
response to MS-LIB prompts. As an option, answers to the 
command prompts may be contained in a responije file. 
Command characters can be used to assist you while giving 
commands to MS-LIB. 



2.1 HOW TO START MS-LIB 

There are three ways to start MS-LIB. With the first 
method, you type the commands as answers to individual 
prompts. By the second method, you type all commands on the 
line used to start MS-LIB. As a third option, you can 
create a response file that contains all the necessary 
commands . 



Summary of Methods to Start MS-LIB 



Method 1 
Method 2 
Method 3 



LIB 

LIB <library><operations> ,<listing> 

LIB P<filespoc> 
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2.1.1 Method 1: Prt>iBpts 

To Start MS-LIB with method 1, type: 

LIB 

MS-LIB will be loaded into memory. MS-LIB will then display 
three text prompts that appear one at a time. You answer 
the prompts, commanding MS-LIB to perform specific tasks. 

The command prompts are summarized here and described more 
fully in the Section 2.2, "Command Prompts." 

Summary of Command Prompts 

PROMPT RESPONSES 

Library File: List filename of library to be 

manipulated. (The default is the 
filename extension .LIB.) 

Operation: List command character (s) followed by 

module name(s) or object filename (s). 
(The default is no changes. The 
default object filename extension is 
.OBJ.) 

List file: List filename for a cross-reference 

listing file. (The default is NUL; 
i.e., no file.) 

NOTE 

The distinction between an 
object file and a module (or 
object module) is that the 
file possesses a drive 
designation (even if it is the 
default drive) and a filename 
extension. Object modules 
possess neither of these. 



RUNNING MS-LIB Page 2-3 

2.1.2 Method 2: Comtand Line 

Type: 

LIB <library><operations> ,<listing> 

The entries following LIB are responses to the 
command prompts. The <library> and <operations> 
fields and all operations entries must be separated 
by one of the command characters plus, minus, or 
asterisk (+, -, or *) . If a cross-reference 
listing is wanted, the name of the file must be 
separated from the last operations entry by a 
comma . 

where: <library> is the name of a library file. MS-LIB 
assumes that the filename extension iA .OBJ, which 
you may override by specifying a different 
extension. If the filename given for the <library> 
field does not exist, MS-LIB will prompt you: 

Library file does not exist. Create? 

Type Yes to create a new library file. Type No to 
abort the library session. 

<operations> is a command to delete a module, 
append an object file as a module, or extract a 
module as an object file from the library file. 
Use the three command characters plus, minus, and 
asterisk to direct MS-LIB to append, delete, or 
extract modules and object files. 

<listing> is the name of the file you want to 
receive the cross-reference listing of PUBLIC 
symbols in the modules in the library. The list is 
compiled after all module manipulation has taken 
place. 

If you type a library filename followed immediately 
by a semicolon, MS-LIB will read through the 
library file and perform a consistency check. No 
changes will be made to the modules in the library 
file. 

If you type a library filename followed immediately 
by a comma and a listing filename, MS-LIB will 
perform its consistency check of the library file, 
then produce the cross-reference listing file. 



Examples: 

LIB PASCA.L-HEAP+HEAP ; 
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This example causes MS-LIB to delete the module 
HEAP from the library file PASCAL. LIB, then append 
the object file HEAP. OBJ as the last module of 
PASCAL. LIB (the module will be named HEAP) . The 
MS-LIB semicolon command character indicates that 
MS-LIB should use the default responses for the 
remaining prompts. Refer to Section 2.3, "Command 
Characters," for more information. 



LIB PASCAL 

This example causes MS-LIB to perform a consistency 
check of the library file PASCAL. LIB. No other 
action is performed. 



LIB PASCAL, PASCROSS. PUB 

This example causes MS-LIB to perform a consistency 
check of the library file PASCAL. LIB, then output a 
cross-reference listing file named PASCROSS .PUB. 

If you have many operations to perform during a library 
session, use the ampersand (&) command character to extend 
the line so that you can type additional object filenames 
and module names. Be sure to always include one of the 
command characters for operations (+, -, *) before the name 
of each module or object filename. 
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2.1.3 Method 3: Response File 

Type: 

LIB P<filespec> 

where: <filespec> is the name of a response file. A 
response file contains answers to the MS-LIB 
prompts. Method 3 permits you to conduct the 
MS-LIB session without user responses to the MS-LIB 
prompts. 

IMPORTANT 

Before using method 3 to start MS-LIB, you 
must first create a response file. 

A response file has one text line for each prompt. 
Responses must appear in the same order as the 
command prompts appear. 

Use command characters in the response file the 
same way you would for responses typed on the 
keyboard. 

When the library session begins, each prompt will 
be displayed with the responses from the response 
file. If the response file does not contain 
answers for all the prompts, MS-LIB will use the 
default responses. (No changes will be made to the 
modules currently in the library file, anS no 
cross-reference listing file will be created.) 

If you type a library filename followed immediately 
by a semicolon, MS-LIB will read through the 
library file and perform a consistency check. No 
changes will be made to the modules in the library 
file. 

If you type a library filename, a carriage return, 
a comma, and then a list filename, MS-LIB will 
perform its consistency check of the library file, 
then produce the cross-reference listing file. 
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Example: 

PASCAL 

+CURSOR+HEAP-HEAP*FOIBLES 

CROSSLST 

This response file causes MS-LIB to delete the 
module HEAP from the PASCAL. LIB library file; 
extract the module FOIBLES and place it in an 
object file named FOIBLES. OBJ; then append the 
object files CURSOR. OBJ and HEAP. OBJ as the last 
two modules in the library. Then, MS-LIB will 
create a cross-reference file named CROSSLST. 
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2.2 COMMAND PROMPTS 

You command MS-LIB by typing responses to three text 
prompts. After you have typed your response to the current 
prompt, the next appears. When the last prompt has been 
Answered, MS-LIB performs its library management functions 
without • further command. You will see the operating system 
prompt when MS-LIB has finished the library session 
successfully. If the library session is unsuccessful, 
MS-LIB will display the appropriate error message. 

MS-LIB prompts you for the name of the library file, the 
operation (s) you want to perform, and the name you want to 
give to a cross-reference listing file (if any) . 

Command Prompts 



Library File; 

Type the name of the library file that you want to 
manipulate. MS-LIB assumes that the filename 
extension is .LIB. You can override this 
assumption by giving a filename extension when you 
type the library filename. Because MS-LIB can 
manage only one library file at a time, only one 
filename is allowed in response to this prompt. 
Additional responses, except the semicolon command 
character, are ignored. 

If you type a library filename and follow it 
immediately with a semicolon command character, 
MS-LIB will perform a consistency check only, then 
return to the operating system. Any errors in the 
file will be displayed. 

If the filename you type does not exist, MS-LIB 
will display the prompt: 

Library file does not exist. Create? 

You must type either Yes or No. 
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Operation; 

Type one of the three command characters for 
manipulating modules (+/ -, *) ; followed 
immediately (no space) by the module name or the 
object filename. The plus sign appends an object 
file as the last module in the library file (see 
further discussion under the description of plus 
sign in the next section) . The minus sign deletes 
a module from the library file. The asterisk 
extracts a module from the library and places it in 
a separate object file, with the filename taken 
from the module name and a filename extension .OBJ. 

When you have a large number of modules to 
manipulate (more than can be typed on one line) , 
type an ampersand (&) as the last character on the 
line. MS-LIB will repeat the Operation: prompt, 
which permits you to type additional module names 
and object filenames. 

MS-LIB allows you to perform operations on modules 
and object files in any order you want. 

More information about modules is given in the 
description of each command character. 

List file; 

If you want a PUBLIC symbols cross-reference list 
for the modules in the library file, type the name 
of a file in which you want MS-LIB to place the 
cross-reference listing. If you do not type a 
filename, no cross-reference listing is generated. 

The response to the List file: prompt is a file 
specification. You can specify a drive (or device) 
designation and a filename extension with the 
filename. The list file is not given a default 
filename extension. If you want the file to have a 
filename extension, you must specify it when typing 
the filename* 

The cross-reference listing file contains two 
lists. The first list is an alphabetical listing 
of all PUBLIC symbols. Each symbol name is 
followed by the name of its module. The second 
list is an alphabetical list of the modules in the 
library. Under each module name is an alphabetical 
listing of the PUBLIC symbols in that module. 
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2.3 COMMAND CHARACTERS 

MS-LIB provides six command characters. Three of the 
command characters are required in response to the 
Operation; prompt. The other three command characters 
provide you with helpful commands to MS-LIB. 

Plus sign Use the plus sign (+) , followed by an 
object filename, to append the object 
file as the last module in the library 
named in response to the Library File: 
prompt. When MS-LIB sees the plus 
sign, it assumes that the filename 
extension is .OBJ. You may override 
this assumption by specifying a 
different filename extension. 

MS-LIB strips the drive designation and 
the extension from the object file 
specification, leaving only the 
filename. For example, if the ohjeirt 
file to be appended as a module to a 
library is 

B:CURSOR.OBJ 

a response to the Operation: prompt of 

+B:CURSOR.OBJ 

will cause MS-Llti to stiip off thf^ 
B: and the .OBJ, leaving only CURSOR. 
This becomes a module named CURSOR in 
the library. 



Minus sign Use the minus sign, followed by a 
module name, to delete a module from 
the library file. MS-LIB then ^ "closes 
up" the disk space left empty by the 
deletion. This cleanup action keeps 
the library file from growing larger 
than necessary. Remember that new 
modules, even replacement modules, are 
added to the end of the file, not put 
into space vacated by deleting modules. 
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Asterisk Use the asterisk, followed by a module 
name, to extract the module from the 
library file and place it into a 
separate object file. The module will 
still exist in the library. (The 
extraction process copies the module to 
a separate object file.) The module 
name is used as the filename. MS-LIB 
adds the default drive designation and 
the filename extension .OBJ. For 
example, if the module to be extracted 
is 

CURSOR 

and the current default disk drive is 
A: , a reponse to the Operation: prompt 
of 

♦CURSOR 

causes MS-LIB to extract the module 
named CURSOR from the library file and 
make it an object file with the file 
specification of: 

A: CURSOR. OB J 

The drive designation and filename 
extension cannot be overridden. You 
can, however, rename the file, giving a 
new filename extension; and/or copy 
the file to a new disk drive, giving a 
new filename and/or filename 
extension . 



Semicolon Use a single semicolon (;), followed 
immediately by a carriage return at 'any 
time after responding to the first 
prompt (i.e., from Library File: on), 
to select default responses to the 
remaining prompts. This feature saves 
time and overrides the need to answer 
additional prompts. 
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NOTE 

Once the semicolon has been 
typed, you can no longer 
respond to any of the prompts 
for that library session. 
Therefore, do not use the 
semicolon to skip over prompts. 
To skip prompts, use carriage 
return. 



Example: 



Library file: FUN 
Operation: +CURSOR; 



The remaining prompt will not appear, 
and MS-LIB will use the default value 
(no cross-reference file) . 

Ampersand Use the ampersand to extend the current 
line. This command character is only 
used in response to the Operation: 
prompt. The number of modules you can 
append is limited only by disk space. 
The number of modules you can replace 
or extract is also limited only by disk 
space. The number of modules you can 
delete is limited by the number of 
modules in the library file. 

The line length for a response to any 
prompt is limited to the line length of 
your system. For a large number of 
responses to the Operation: prompt, 
place an ampersand at the end of a 
line. MS-LIB will display the 
Operation: prompt again, and then you 
can type more responses. For example: 



Library File: FUN 

Operation: +CURSOR-HEAP+HEAP*FOIBLES& 

Operation: *INIT+ASSUME+RIDE; 

MS-LIB will delete the module HEAP; 
extract the modules FOIBLES and INIT 
(creating two files, FOIBLES. OBJ and 
INIT. OBJ); then append the object 
files CURSOR, HEAP, ASSUME, and RIDE. 
Note that MS-LIB allows you to type 
your Operation: reponses in any order. 
You may use the ampersand character as 
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many times as needed. 



CONTROL-C Use <CONTROL-C> to abort the library 
session at any time. If you type an 
incorrect response, such as the wrong 
filename or .nodule name, or an 
incorrectly spelled filename or module 
name» you must press <CONTROL-C> to 
exit MS-LIB; then you must restart 
MS-LIB. If the error has been typed 
and you have not pressed the <RETURN> 
key, you may delete the erroneous 
characters for that line only. 
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Summary of Command Characters 

Character Action 

+ Appends an object file as the last 
module 

Deletes a module from the library 

* Extracts a module and places in an 
object file 

; Use default responses to remaining 
prompts 

& Extends current physical line; repeats 
command prompt 

CONTROL-C Aborts library session 



CHAPTER 3 
ERROR MESSAGES 

The following are MS-LIB error messages: 

<syinbol> is a multiply defined PUBLIC. Proceed? 

Cause: Two modules define the same public symbol. 
You are asked to confirm the removal of the 
definition of the old symbol. 

Cure: Remove the PUBLIC declaration from one of 
the object modules and recompile or reassemble. 
If you respond No, the library will be left in 
an indeterminate state. 

Allocate error on VM.TMP 

Cause: Out of disk space 

Cannot create extract file 

Cause: No room in directory for extract file 

Cannot create list file 

Cause: No room in directory for library file 

Cannot nest response file 

Cause: §filespec in response (or indirect) file 

MS-LIB cannot open VM.TMP 

Cause: There is no room for VM.TMP in disk 
directory 

Cannot write library file 

Cause: Out of disk space 

Close error on extract file 

Cause: Out of disk space 

Error: An internal error has occurred 
Contact Microsoft Corporation 

Fatal Error: Cannot open input file 

Cause: You mistyped an object filename 
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Fatal Error: Module is not in the library 

Cause: You tried to delete a module that is not in 
the library 

Input file read error 

Cause: Bad ob5ect module or faulty disk 

Invalid object module/library 

Cause: Bad object module and/or library 

Library Disk is full 

Cause: No more room on disk 

Listing file write error 

Cause; Out of disk space 

No library file specified 

Cause: No response to Library File: prompt 

Read error on VM.TMP 

Cause: Disk not ready for read 

Symbol table capacity exceeded 

Cause: Too many public symbols (about 30K chars in 
symbols) 

Too many object modules 

Cause: More than 500 object modules 

Too many public symbols 

Cause: 1024 public symbols maximum 

Write error on library/extract file 
Cause: Out of disk space 

Write error on VM.TMP 

Cause: Out of disk space 
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drives is a more practical configuration. 
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CHAPTER 1 
INTRODOCTIOH 



1.1 FEATURES OP MS-CREF 

The Microsoft CREF Cross-Ref erence Utility can help you in 
debugging your assembly language programs. MS-CREF outputs 
an alphabetical listing of all the symbols to a special file 
created by your assembler. With this listing » you can 
quickly locate all occurrences of any symbol in your source 
program by line number. 

The cross-reference listing produced by MS-CREF gives, you 
symbol locations, speeding your search and allowing faster 
debugging . 

The MS-CREF listing is used with the symbol table produced 
by your assembler. 

The symbol table listing shows the value, type, and length 
of each symbol. This information is needed to correct 
erroneous symbol definitions or uses. 
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1.2 OVERVIEW OF MS-CREP OPERATION 

MS-CREF produces a file with cross-references for symbolic 
names in your program. 

First, you must create a cross-reference file with the 
assembler. Then, MS-CREF converts this cross-reference file 
(which has the filename extension .CRF) into an alphabetical 
listing of the symbols in the file. The cross-reference 
listing file is given the default filename extension .RRF. 

Beside each symbol in the listing, MS-CREF lists the line 
numbers where the symbol occurs in the source program. The 
line numbers are listed in ascending sequence. The line 
number where the symbol is defined is indicated by a pound 
sign (#) . 
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Figure 1 illustrates the MS-CREF operation, 
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Figure 1. MS-CREF Operation 



CHAPTER 2 
RONNING MS-CREF 



Running MS-CREF requires two types of commands: a command 
to start MS-CREF and answers to command prompts. You type 
all the commands to MS-CREF on a command line or in response 
to MS-CREF prompts. Command characters can be used to 
assist you while giving commands to MS-CREF. 

Before you can use MS-CREF to create the cross-reference 
listing, you must first create a cross-reference file using 
your assembler. This step is described in the next section. 



2.1 HOW TO CREATE A CROSS-REFERENCE FILE 

A cross-reference file is created during an assembly 
session. To create a cross-reference file, use the 
Microsoft Macro Assembler and answer the fourth command 
prompt with the name of the cross-reference file you want to 
create. 

The fourth assembler prompt is: 

Cross-reference tNUL.CRF] : 

If you do not type a filename in response to this prompt, or 
if you use the default response, the assembler will not 
create a cross-reference file. Therefore, you must type a 
filename if you want to create a cross-reference file. 

You may also specify which drive or device you want the file 
saved on, and the filename extension (if different from 
.CRF) . If you assign a- filename extension other than .CRF, 
you must specify the filename extension when naming the file 
in response to the first MS-CREF prompt. (Refer to Section 
2.2, "How to Start MS-CREF," for a description of MS-CREF 
prompts.) 
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You are now ready to use MS-CREF to convert the 

cross-reference file produced by the assembler into a 
cross-reference listing. 



2.2 HOW TO START MS-CREF 

MS-CREF may be started two ways. By the first method, you 
type the commands as answers to individual prompts. By the 
second method, you type all commands on the line used to 
start MS-CREF. 



Summary of Methods to Start MS-CREF 

Method I CREF 

Method 2 CREF <crf f ile> , <list ing> 
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2.2.1 Method 1: Prompts 

To start MS-CREF using prompts, type: 

CREF 

MS-CREF will be loaded into memory. Then, MS-CREF displays 
two text prompts that appear one at a time. You answer the 
prompts to command MS-CREF to convert a cross-reference file 
into a cross-reference listing. 

Command Prompts 

Cros s reference [ .CRF] ; 

Type the name of the cross-reference file you want 
MS-CREF to convert to a cross-reference listing. 
The filename is the name you specified when you 
directed the assembler to produce the 
cross-reference file. 

MS-CREF assumes that the filename extension is 
.CRF. If you do not specify a filename extension 
when you type the cross-reference filename, MS-CREF 
will look for a file with the name you specify and 
the filename extension .CRF. If your 
cross-reference file has a different extension, 
specify that extension when typing the filename. 

Refer to Chapter 4, "Format of MS-CREF Compatible 
Files," for a description of what MS-CREF expects 
to see in the cross-reference file. You will need 
this information only if your cross-reference file 
was not produced by a Microsoft assembler. 

Listing [erf file. REF] ; 

Type the name you want the cross-reference listing 
file to have. MS-CREF will automatically give the 
cross-reference listing the filename extension 
. REF . 

If you want you cross-reference listing to have the 
same filename as the cross-reference file but with 
the filename extension .REF, simply press the 
<RETURN> key when the Listing: prompt appears. If 
you want your cross-reference listing file to be 
named anything else, or to have any other filename 
extension, you must type a response following the 
Listing: prompt. 

If you want the listing file placed on a drive or 
device other than the default drive, specify that 
drive or device when typing your response to the 
Listing: prompt. 
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2.2.2 Method 2: Conand Line 

To start MS-CREF using the command line, type: 

CREF <crffile>,<listing> 

MS-CREF will be loaded into memory. Then MS-CREF converts 
your cross-reference file into a cross-reference listing. 

The entries following CREF are responses to the command 
prompts. The <crffile> and <listing> fields must be 
separated by a comma. 



where: <crffile> is the name of the cross-reference file 
produced by your assembler. MS-CREF assumes that 
the filename extension is .CRF. You ihay override 
this default by specifying a different extension. 
If the file named for the <crffile> does not exist, 
MS-CREF will display the message.: 

Fatal I/O Error 110 

in File: <crf'f ile>.CRF 

MS-CREt will be aborted and the operating system 
prompt will appear. 

<listing> is the name of the file you want to 
concain the cross-reference listing of symbols in 
your program. 

To select the default filename and extension for 
the listing file, type a semicolon after the 
<crffile> name. Refer to the "Command Characters" 
section for more information on how to use the 
semicolon. 



Examples: 

CREF FUN; 

This example causes MS-CREF to process the 
cross-reference file FUN. CRF and to produce a 
listing file named FUN.REF. 
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To give the listing file a different filename* 
extension, or destination, simply specify it when 
you type the command line. 

CREF FUN »B: WORK. ARG 

This example causes MS-CREP to process the 
cross-reference file named RUN.CRF and to produce a 
listing file named WORK. ARG, which will be placed 
on the disk in drive B: . 
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2.3 COMMAND CHARACTERS 

MS-CREF provides two command characters. 

Semicolon Use a single semicolon (;), followed 
immediately by a carriage return, at any 
time after responding to the Cross 
reference: prompt to select the default 
response to the Listing: prompt. This 
feature saves time and overrides the need to 
answer the Listing: prompt. 

If you use the semicolon, MS-CREF gives the 
listing file the filename of the 
cross-reference file and the default 
filename extension .REF. 

Example: 

Cross reference ( .CRF] : FUN; 

MS-CREF will process the cross-reference 
file named FUN. CRF and output a listing file 
named FUN. REF. 



CONTROL-C Use <CONTROL-C> at any time to abort the 
MS-CREF session. If you make a mistake (for 
example, typing the wrong filename or 
incorrectly spelling a filename) , you must 
press <CONTROL-C> to exit MS-CREF, and then 
restart MS-CREF. If the error has been 
typed but you have not pressed the <RETURN> 
key, you may delete the erroneous 
characters, but for that line only. 



2.4 FORMAT OF CROSS-REFERENCE LISTINGS 

The cross-reference listing is an alphabetical list of all 
the symbols in your program. Each page begins with the 
title of the program or program module. Then the symbols 
are listed. Following each symbol name is a list of the 
line numbers where the symbol occurs in your program. The 
line number for the definition has a pound sign (#) appended 
to it. 

An example of a cross-reference listing appears in the next 
section. 
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2.4.1 Example Of Cross-Reference Listing 



MS-CREF 



(vers no.) 



(date) 



ENTX PASCAL entry for initializing progranis< — comes from 

TITLE directive 



Symbol Cross-Reference 



(# is definition) Cref-1 



AAAXQQ 



37# 



38 



BEGHQQ . . 


. 83 


84» 


154 


176 


BEGOQQ . . 


. 33 


162 






BEGXQQ . . 


. 113 


126# 


164 


223 


CESXQQ . . 


. . 97 


99# 


129 




CLNEQQ . . 


. . 67 


681 






CODE . . . 


. . 37 


182 






CONST . . . 


. 104 


104 


105 


110 


CRCXQQ . . 


. . 93 


94« 


210 


215 


CRDXQQ . . 


. . 95 


96# 


216 




CSXEQQ . . 


. 65 


66« 


149 




CURHQQ . . 


• ^5 


86« 


155 




DATA . . . 


. . 64# 


64 


100 


110 


DGROUP . . 


. . 110# 


111 


111 


111 


DOSOFF . . 


. . 98# 


198 


199 




DOSXQQ . . 


. . 184 


204« 


219 




ENDHQQ . . 


. . 87 


88# 


158 




ENDOQQ . . 


. . 33# 


195 






ENDllQQ . . 


. . 31# 


197 






ENDXQQ . . 


. . 184 


194# 






ENJDYQQ . . 


. . 32# 


196 






ENTGQQ . . 


. . 30# 


187 






ENTXCM . . 


. . 182# 


183 


221 




FREXQQ . . 


. 169 


170# 


178 




HDRFQQ . . 


. . 71 


721 


151 




HDRVQQ . . 


. 73 


741 


152 




HEAP . . . 


. . 42 


44 


110 




HEAPBEG. . 


. 54# 


153 


172 




HEAPLOW. . 


. . 43 


171 






TNIUQQ . . 


. . 31 


161 






MAIN STARTUI 


> 109« 


111 


180 




MEMORY . . 


. . 42 


481 


48 


49 


PNUXQQ . . 


. 69 


70 


150 




RECEQQ . . 


' . 81 


82# 







127 153 171 172 



109 



110 
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REFEQQ .... 77 78# 

REPEQQ .... 79 80« 

RESEQQ .... 75 761 148 

ENTX PASCAL entry £or initializing programs 



Symbol Cross-Reference 



(# is definition) Cre£-2 



SKTOP. . . 


. . 59# 






SMLSTK . . 


. . 135 


137# 




STACK. . . 


. 53« 


53 


60 


STARTMAIN. 


. . 163 


186» 


200 


STKBQQ . . 


. 89 


90f 


146 


STKHQQ . . 


. 91 


92# 


160 



110 



CHAPTER 3 
ERROR MESSAGES 



All errors cause MS-CREP to abort. Control is returned to 
the operating system. 

All error messages are displayed in the following format: 

Fatal I/O Error <error number> 
in File: <filename> 



where: <filename> is the name of the file where the error 
occurs. 

<error number> is one of the numbers in the 
following list of errors: 



ERROR MESSAGES Page 3-2 



Number Error 

101 Hard data error 

Unrecoverable disk I/O error 

101 Device name error 

Illegal device specification (for example, 
XrFOO.CRF) 

103 Internal error 

Report to Microsoft Corporation 

104 Internal error 

Report to Microsoft Corporation 

105 Device offline 

Disk drive door open, no printer attached, or 
similar device is offline. 

106 Internal error 

Report to Microsoft Corporation 

108 Disk full 

110 File not found 

111 Disk is write protected 

112 Internal error 

Report to Microsoft Corporation 

113 Internal error 

Report to Microsoft Corporation 

114 Internal error 

Report to Microsoft Corporation 

115 Internal error 

Report to Microsoft Corporation 



CHAPTER 4 
FORMAT OF MS-CREF COMPATIBLE FILES 



MS-CREF will process files other than those generated by 
Microsoft's assembler, as long as the file conforms to the 
valid MS-CREF format. 



4.1 MS-CREF FILE PROCESSING 

MS-CREF reads a stream of bytes from the cross-reference 

file (or source file) , sorts them, then emits them as a 

printable listing file (the .REF file) . The symbols are 

held in memory as a sorted tree. References to the symbols 
are held in a linked list. 

MS-CREF keeps track of line numbers in the source file by 
the number of end-of-line characters it encounters. 
Therefore, every line in the source file must contain at 
least one end-of-line character (see chart below) . 

MS-CREF places a heading at the top of every page of the 
listing. The name MS-CREF uses is passed by your assembler 
from a TITLE (or similar) directive in your source program. 
The title must be followed by a title symbol (see chart 
below) . If MS-CREF encounters more than one title symbol in 
the source file, it will use the last title read for all 
page headings. If MS-CREF does not encounter a title symbol 
in the file, the title line on the listing will be blank. 
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4.2 FORMAT OP SODRCB FILES 

MS-CREF uses the first three bytes of the source file as 

format specification data. The rest of the file is 

processed as a series of records that either begin or end 
with a byte that identifies the type of record. 



4.2.1 First Three Bytes 

The PAGE directive in your assembler, which takes arguments 
for page length and line length, will pass the following 
information to the cross-reference file: 

First Byte 

The number of lines to be printed per page (page 
length range is from 1 to 255 lines) . 

Second Byte 

The number of characters per line (line length 
range is from 1 to 132 characters) . 

Third Byte 

The Page Symbol (07) that tells MS-CREF that the 
two preceding bytes define listing page size. 

If MS-CREF does not see these first three bytes in the file, 
it uses default values for page size (page length is 58 
lines; line length is 80 characters). 



4.2.2 Control Syabols 

The two tables below show the types of records that MS-CREF 
recognizes and the byte values and placement it uses to 
recognize record types. 

Records have a control symbol (which identifies the record 
type) either as the first byte of the record or as the last 
byte. 
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Records That Begin with a Control Symbol 

Byte 

Value* Control Symbol Subsequent Bytes 

01 Reference symbol Record is a reference 

to a symbol name 

(1 to 80 characters) 

02 Define symbol Record is a definition 

of a symbol name 

(1 to 80 characters) 

04 End-of-line (none) 

05 End-of-file lAH 



Records That End with a Control Symbol 

Byte 

Value* Control Symbol Preceding Bytes 

06 Title defined Record is title text 

(1 to 80 characters) 

07 Page length/ One byte for page length 
line length followed by one byte 

for line length 



♦For all record types, the byte value represents a control 
character, as follows: 



01 


Control-A 


02 


Control-B 


04 


Control-D 


05 


Control-E 


06 


Control-F 


07 


Control-G 
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The Control Symbols are defined as follows: 

Reference symbol 

Record contains the name of a symbol that is 
referenced. The name may be from 1 to 80 ASCII 
characters long. Additional characters are 
truncated. 

Define symbol 

Record contains the name of a symbol that is 
defined. The name may be from 1 to 80 ASCII 
characters long. Additional characters are 
truncated. 

End-of-line 

Record is an end-of-line symbol character only (04H 
or Control-D) . 

End-of-f ile 

Record is the end-of-file character (lAH) . 

Title defined 

ASCII characters of the title are to be printed at 
the top of each listing page. The title may be 
from 1 to 80 characters long. Additional 
characters are truncated. The last title 
definition record encountered is used for the title 
placed at the top of all pages of the listing. If 
a title definition record is not encountered, the 
title line on the listing will be left blank. 

Page length/line length 

The first byte of the record contains the number of 
lines to be printed peir page (range is from 1 to 
255 lines) . The second byte contains the number of 
characters to be printed per page (range is from 1 
to 132 characters) . The default page length is 58 
lines. The default line length is 80 characters. 

The following table illustrates CRF file record contents by 
byte and length of record. 
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Sununary of CRF File Record Contents 
Byte Contents Length of Record 

01 syn»bol_naine 2-81 bytes 

02 syinbol_naine 2-81 bytes 

04 1 byte 

05 lA 2 bytes 
title_text 06 2-81 bytes 
PL LL 07 3 bytes 



INDBX 



.CRF (default extension) . . . 1-2 
.REP (default extension) . . . 1-2 
; (command character) .... 2-6 

Command Characters 2-6 

; .2-6 

CONTROL-C 2-6 

Command Prompts 

Cross-reference [.CRF] . . . 2-3 
Listing Icrf f ile.REF] . . , 2-3 

Control symbols 4-2 » 4-4 

CONTROL-C (command character) 2-6 

Creating a cross-reference file 2-1 

Cross reference [.CRF] (command prompt) 2-3 

Default extensions 

.CRF 1-2 

.REF 1-2 

Error messages 3-1 

Format of cross-reference listings 2-6 
Format of MS-CREF compatible files 4-1 

Listing (erf file. REF] (command prompt) 2-3 

Method 1 2-3 

Method 2 2-4 

Overviews 

MS-CREF operation 1-2 

Running MS-CREF 2-1 

Starting 

Method 1 2-3 

Method 2 .... 2-4 

Starting MS-CREF 2-2 

Summary of CRF file record contents 4-5 
Summary of methods to start . 2-2 



Microsoft. DEBUG 



utility 



for 8086 and 8088 Microprocessors 



Microsoft Corporation 



System Requireaents 



The Microsoft DEBUG Utility requires: 

A memory minimum that is program-dependent: 
13K bytes for code 
Run space is program-dependent 

Disk drive (s) : 

1 disk drive if and only if output is sent to the 
same physical disk from which the input was taken. 
Microsoft DEBUG does not allow time to swap disks 
during operation on a one-drive configuration. 
Therefore, two disk* drives is a more practical 
configuration. 
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CHAPTER 1 
INTRODUCTION 



1.1 OVERVIEW OF DEBUG 

The Microsoft DEBUG Utility (DEBUG) is a debugging program 
that provides a controlled testing environment for binary 
and executable object files. Note that EDLIN is used to 
alter source files; DEBUG is EDLIN' s counterpart for binary 
files. DEBUG eliminates the need to reassemble a program to 
see if a problem has been fixed by a minor change. It 
allows you to alter the contents of a file or the contents 
of a CPU register, and then to immediately reexecute a 
program to check on the validity of the changes. 

All DEBUG commands may be aborted at any time by pressing 
<CONTROL-C>. <CONTROL-S> suspends the display, so that you 
can read it before the output scrolls away. Entering any 
key other than <CONTROL-C> or <CONTROL-S> restarts the 
display. All of these commands are consistent with the 
control character functions available at the MS-DOS command 
level . 



1.2 HOW TO START DEBUG 

DEBUG may be started two ways. By the first method, you 
type all commands in response to the DEBUG prompt (a 
hyphen). By the second method, you type all commands on the 
line used to start DEBUG. 

Summary of Methods to Start DEBUG 



Method 1 DEBUG 

Method 2 DEBUG f<filespec> [<arglist>]] 
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1.2.1 Method 1: DEBUG 

To start DEBUG using method 1, type: 

DEBUG 

DEBUG responds with the hyphen (-) prompt, signaling that it 
is ready to accept your commands. Since no filename has 
been specified, current memory, disk sectors, or disk files 
can be worked on by using other commands. 

Warnings 



1. When DEBUG (Version 2.0) is started, it sets up a 
program header at offset in the program work 
area. On previous versions of DEBUG, you could 
overwrite this header. You can still overwrite the 
default header if no <filespec> is given to DEBUG. 
If you are debugging a .COM or .EXE file, however, 
do not tamper with the program header below address 
5CH, or DEBUG will terminate. 

2. Do not restart a program after the "Program 
terminated normally" message is displayed. You 
must reload the program with the N and L commands 
for it to run properly. 



1.2.2 Method 2: Coninand Line 

To start DEBUG using a command line, type: 

DEBUG [<filespec> r<arglist>] 

For example, if a <filespec> is specified, then the 
following is a typical command to start DEBUG: 

DEBUG FIuE.EXE 

DEBUG then loads FILE. EXE into memory starting at 100 
hexadecimal in the lowest available segment. The BX:CX 
registers are loaded with the number of bytes placed into 
memory. 

An ''arglist> may be specified if <filespec> is present. The 
<arglist> is a list of filename parameters and switches that 
are to be passed to the program <filespec>. Thus, when 
<filespec> is loaded into memory, it is loaded as if it had 
been started with the command: 
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<filespec> <arglist> 

Here, <filespec> is the file to be debugged, and the 

<arglist> is the rest of the conunand line that is used when 

<filespec> is invoked and loaded into memory. 



CHAPTER 2 
COMMANDS 



2.1 COMMAND INFORMATION 

Each DEBUG command consists of a single letter followed by 
one or more parameters. Additionally, the control 
characters and the special editing functions described in 
the MS-DOS User's Guide , apply inside DEBUG. 

If a syntax error occurs in a DEBUG command, DEBUG reprints 
the command line and indicates the error with an up-arrow 
(^) and the word "error." 

For example: 

dcs:100 cs:110 
'' error 

Any combination of uppercase and lowercase letters may be 
used in commands and parameters. 

The DEBUG commands are summarized in Table 2.1 and are 
described in detail, with examples, following the 
description of command parameters. 
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Table 2.1 DEBUG Conunands 



DEBUG Command 

A[<addcess>] 

C<range> <address> 

D[<range>] 

E<address> [<list>l 

F<range> <list> 

G[=<address> [<address>. . .] ] 

H<value> <value> 

I<value> 

L[<address> (<drive><record><record>] ] 

M<range> <address> 

N<f ilename> [<f ilename>] 

0<value> <byte> 

Q 

R{<register-name>] 

S<range> <list> 

T [=<address>][ <value>] 

U(<range>l 

W[<address> t<drive><record><record>l ] 



Function 

Assemble 

Compare 

Dump 

Enter 

Fill 

Go 

Hex 

Input 

Load 

Move 

Name 

Output 

Quit 

Register 

Search 

Trace 

Unassemble 

Write 
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2.2 PAHAMETERS 

All DEBUG commands accept parameters, except the Quit 
command. Parameters may be separated by delimiters (spaces 
or commas) , but a delimiter is required only between two 
consecutive hexadecimal values. Thus, the following 
commands are equivalent: 

dcs:100 110 
d cs:100 110 
d,cs:100,110 



PARAMETER DEFINITION 

<drive> A one-digit hexadecimal value to indicate which 
drive a file will be loaded from or written to. 
The valid values are 0-3. These values 
designate the drives as follows: 0=A; , 1=B: , 
2=C:, 3=D:. 

<byte> A two-digit hexadecimal value to be placed in or 
read from an address or register. 

<record> A 1- to 3-digit hexadecimal value used to 
indicate the logical record number on the disk 
and the number of disk sectors to be written or 
loaded. Logical records correspond to sectors. 
However, their numbering differs since they 
represent the entire disk space, 

<value> A hexadecimal value up to four digits used to 
specify a port number or the number of tiroes a 
command should repeat its functions. 

<address> A two-part designation consisting of either an 
alphabetic segment register designation or a 
four-digit segment address plus an offset value. 
The segment designation or segment address may 
be omitted, in which case the default segment is 
used. OS is the default segment for all 
commands except G, L, T, U, and W, for which the 
default segment is CS. All numeric values are 
hexadecimal. 

For example: 

CS:010G 
04BA:0100 

The colon is required between a segment 
designation (whether numeric or alphabetic) and 
an offset. 
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<range> Two <address>es: e.g., <address> <address>; or 
one <address>, an L, and a <value>: e.g., 
<address> L <value> where <value> is the number 
of lines the command should operate on, and L80 
is assumed. The last form cannot be used if 
another hex value follows the <range>, since the 
hex value would be interpreted as the second 
<address> of the <range>. 

Examples: 

CS:100 110 
CStlOO L 10 
CS:100 

The following is illegal: 

CS:100 CS:110 
" error 



The limit for <range> is 10000 hex. To specify 
a <value> of 10000 hex within four digits, type 
0000 (or 0) . 

<list> A series of <byte> values or of <string>s. 
<list> must be the last parameter on the command 
line. 

Example: 

fcs:100 42 45 52 54 41 

<string> Any number of characters enclosed in quote 
marks. Quote marks may be either single (') or 
double("). If the delimiter quote marks must 
appear within a <string>, the quote marks must 
be doubled. For example, the following strings 
are legal: 

'This is a "string" is okay.' 
'This is a ''string'' is okay.' 

However, this string is illegal: 

'This is a 'string' is not.' 

Similarly, these strings are legal: 

"This is a 'string' is okay." 
"This is a ""string"" is okay." 
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However, this string is illegal: 

"This is a "string" is not." 

Note that the double quote marks are not 
necessary in the following strings: 

"This is a ' 'string'' is not necessary." 
'This is a ""string"" is not necessary.' 

The ASCII values o£ the characters in the string 
are used as a <list> of byte values. 
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NAME 

Assemble 

PURPOSE 

Assembles 8086/8087/8088 mnemonics directly 
into memory. 



SYNTAX 



A[<address>] 



COMMENTS 

If a syntax error is found, DEBUG responds with 

'^Error 

and redisplays the current assembly address. 

All numeric values are hexadecimal and must be 
entered as 1-4 , characters. Prefix mnemonics 
must be specified in front of the opcode to 
which they refer. They may also be entered on 
a separate line, . 

The segment override mnemonics are CS:, OS:, 
ES:, and SS:. The mnemonic, for the far return 
is RETF. String manipulation mnemonics must 
explicitly state the string size. For example, 
use MOysw to move word strings and MOVSB to 
move byte strings. 

The assembler will automatically assemble 
short, near or far jumps and calls, depending 
on byte displacement to the destination 
address. These may be overridden with the NEAR 
or FAR prefix. For example: 

0100:0500 JMP . 502 . , ; a .2-byte short jump 
0100:0502 JMP NEAR 505 ; a 3-byte near jump 
0100:505 JMP FAR 50A ; a 5-byte far jump 

The NEAR prefix may be abbreviated to NE, but 
the FAR prefix cannot be abbreviated.. 

DEBUG cannot tell whether some operands refer 
to a word memory location or to a byte memory 
location. In this case, the data type must be 
explicitly stated with the prefix "WORD PTR" or 
"BYTE PTR". Acceptable abbreviations are "WO" 
and "BY". For example: 

NEG BYTE PTR [128] 
DEC WO ISI] 
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DEBUG also cannot tell whether an operand 
refers to a memory location or to an immediate 
operand. DEBUG uses the common convention that 
operands enclosed in square brackets refer to 
memory. For example: 



MOV 
MOV 



AX, 21 
AX, [21] 



Load AX with 21H 

Load AX with the 

contents 

of memory location 21H 



Two popular pseudo-instructions are available 
with Assemble. The DB opcode will assemble 
byte values directly into memory. The DW 
opcode will assemble word values directly into 
memory. For example: 

DB 1,2, 3, 4, "THIS IS AN EXAMPLE" 
DB 'THIS IS A QUOTE: "' 
DB "THIS IS A QUOTE: •" 



DW 



1000 , 2000 , 3000 , "BACH* 



Assemble supports all forms of register 
indirect commands. For example: 

ADD BX,34(BP+2] . (SI-1] 
POP [BP+DI] 
PUSH (SIl 

All opcode synonyms are also supported. For 
example: 



LOOPZ 
LOOPE 



100 
100 



JA 
JNBE 



200 
200 



For 8087 opcodes, the WAIT or FWAIT must be 
explicitly specified. For example: 



FWAIT FADD ST, ST (3) 
LD TBYTE PTR [BXl 



; This line will assemble 
; an FWAIT prefix 
; This line will not 
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NAME 

Compare 



PURPOSE 

Compares the portion of memory specified by 
<range> to a portion of the same size beginning 
at <address>. 



SYNTAX 



C<range> <address> 



COMMENTS 

If the two areas of memory are identical, there 
is no display and DEBUG returns with the MS-DOS 
prompt. If there are differences, they are 
displayed in this format: 

<addressl> <bytel> <byte2> <address2> 



EXAMPLE 

The following commands have the same effect: 

C100,1FF 300 

or 

CIOOLIOO 300 

Each command compares the block of memory from 
100 to IFFH with the block of memory from 300 
to 3FFH. 
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NAME 

Dunp 

PURPOSE 

Displays the contents of the specified region 
of memory. 



SYNTAX 



D[<range>1 



COMMENTS 



If a range of addresses is specified, the 
contents of the range are displayed. If the D 
command is typed without parameters, 128 bytes 
are displayed at the first address (DSilOO) 
after the address displayed by the previous 
Dump command. 

The dump is displayed in two portions: a 
hexadecimal dump (each byte is shown in 
hexadecimal value) and an ASCII dump (the bytes 
are shown in ASCII characters). Nonprinting 
characters are denoted by a period (.) in the 
ASCII portion of the display. Each display 
line shows 16 bytes with a hyphen between the 
eighth and ninth bytes. At times, displays are 
split in this manual to fit them on the page. 
Each displayed line begins on a 16-byte 
boundary. 

If you type the command: 

dc8:100 110 

DEBUG displays the dump in the following 
format: 

04BA:0100 42 45 52 54 41 ... 4E 44 TOM SAWYER 

If you type the following command: 

D 

the display is formatted as described above. 
Each line of the display begins with an 
address, incremented by 16 from the address on 
the previous line. Each subsequent D (typed 
without parameters) displays the bytes 
immediately following those last displayed. 
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If you type the command: 

DCS: 100 L 20 

the display is formatted as described above , 
but 20H bytes are displayed. 

If then you type the command: 

DCS: 100 115 

the display is formatted as described above, 
but all the bytes in 'the range of lines from 
lOOH to 115H in the CS segment are displayed. 



DEBUG (E)nter Page 2-11 

NAME 

Enter 



PURPOSE 



SYNTAX 



Enters byte values into memory at the specified 
<address> . 



E<address>[ <list>I 



COMMENTS 

If the optional <list> of values is typed, the 
replacement of byte values occurs 
automatically. (If an error occurs, no byte 
values are changed.) 

If the <address> is typed without the optional 
<list>, DEBUG displays the address and its 
contents, then repeats the address on the next 
line and waits for your input. At this point, 
the Enter command waits for you to perform one 
of the following actions': 

1. Replace a byte value with a value you type. 
Simply type the value after the current 
value. If the value typed in is not a 
legal hexadecimal value or if more than two 
digits are typed, the illegal or extra 
character is not echoed. 

2. Press the <SPACE> bar to advance to the 
next byte. To change the value, simply 
type the new value as described in (1.) 
above. If you space beyond an 8-byte 
boundary, DEBUG starts a new display line 
with the address displayed at the 
beginning. 

3. Type a hyphen (-) to return to the 
preceding byte. If you decide to change a 
byte behind the current position, typing 
the hyphen returns the current position to 
the previous byte. When the hyphen is 
typed, a new line is started with the 
address and its byte value displayed. 

4. Press the <RETURN> key to terminate the 
Enter command. The <RETURN> key may be 
pressed at any byte position. 
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EXAMPLE 

Assume that the following conunand is typed: 

ECS: 100 

DEBUG displays: 

04BA:0100 EB._ 

To change this value to 41, type 41 as shown: 

.04BA:0100 EB.41_ 

To step through the subsequent bytes, press the 
<SPACE> bar to see: 

04BA:0100 EB.41 10. 00. BC._ 

To change BC to 42: 

04BA:0100 EB.41 10. 00. BC.42_ 

Now, realizing that 10 should be 6P, type the 
hyphen as many times as needed to return to 
byte 0101 (value 10) , then replace 10 with 6P: 

04BA:0100 EB.41 10. 00. BC.42- 
04BA:0102 00.- 
04BA:0101 10.6F_ 

Pressing the <RETURN> key ends the Enter 
command and returns to the DEBUG command level. 
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NAME 

Pill 

PURPOSE 

Fills the addresses in the <range> with the 
values in the <list>. 



SYNTAX 



F<range> <list> 



COMMENTS 

If the <range> contains more bytes than the 
number of values in the <list>, the <list> will 
be used repeatedly until all bytes in the 
<range> are filled. If the <list> contains 
more values than the number of bytes in the 
<range>» the extra values in the <list> will be 
ignored. If any of the memory in the <range> 
is not valid (bad or nonexistent) , the error 
will occur in all succeeding locations. 



EXAMPLE 



Assume that the following command is typed: 

F04BA:100 L 100 42 45 52 54 41 

DEBUG fills memory locations 04BA:100 through 
04BA:1FF with .' the bytes specified. The five 
values are repeated until all lOOH bytes are 
filled. 
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NAME 

Go 

PURPOSE 

Executes the program currently in memory. 



SYNTAX 

G(=<address>I <address>. . .] ] 



COMMENTS 

If only the Go command is typed, the program 
executes as if the program had run outside 
DEBUG . 

If =<address> is set, execution begins at the 
address specified. The equal sign («) is 
required, so that DEBUG can distinguish the 
start =<address> from the breakpoint 
<address>es. 

With the other optional addresses set, 
execution stops at the first <address> 
encountered « regardless of that address* 
position in the list of addresses to halt 
execution or program branching. When program 
execution reaches a breakpoint, the registers, 
flags, and decoded instruction are displayed 
for the last instruction executed. (The result 
is the same as if you had typed the Register 
command foe the breakpoint address.) 

Up to ten breakpoints may be set. Breakpoints 
may be set only at addresses containing the 
first byte of an 8086 opcode. If more than ten 
breakpoints are set, DEBUG returns the HP Error 
message. 

The user stack pointer must be valid and have 6 
bytes available for this command. The G 
command uses an IRET instruction to cause a 
jump to the program under test. The user stack 
pointer is set, and the user flags, Code 
Segment register, and Instruction Pointer are 
pushed on the user stack. (Thus, if the user 
stack is not valid or is too small, the 
operating system may crash.) An interrupt code 
(OCCH) is placed at the specified breakpoint 
address (es) . 

When an instruction with the breakpoint code is 
encountered, all breakpoint addresses are 
restored to their original instructions. If 
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execution is not halted at one ' of the 
breakpoints, the interrupt codes ate not 
replaced with the original instructions. 



EXAMPLE 



Assume that the following command is typed: 

GCS:7550 

The program currently in memory executes up to 
the address 7550 in the CS segment. DEBUG then 
displays registers and flags, after which the 
Go command is terminated. 

After a breakpoint has been encountered, if you 
type the Go command again, then the program 
executes just as if you had typed the filename 
at the MS-DOS command level. The only 
difference is that program execution begins at 
the instruction after the breakpoint rather 
than at the usual start address. 



DEBUG (H)ex Page 2-16 



NAME 

Hex 



PURPOSE 

Performs hexadecimal arithmetic on the two 
parameters specified. 



SYNTAX 

H<value> <value> 



COMMENTS 

First, DEBUG adds the two parameters, then 
subtracts the second parameter from the first. 
The results of the arithmetic are displayed on 
one line; first the sum, then the difference. 



EXAMPLE 

Assume that the following command is typed: 

H19F lOA 

DEBUG performs the calculations and then 
displays the result: 

02A9 0095 
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NAME 

Input 

PURPOSE 

Inputs and displays one byte from the port 
specified by <value>. 



SYNTAX 

I<value> 



COMMENTS 

A 16-bit port address is allowed. 



EXAMPLE 

Assume that you type the following command; 

I2F8 

Assume also that the byte at the port is 42H, 
DEBUG inputs the byte and displays the value: 

42 
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NAME 

Load 



PURPOSE 

Loads a file into memory. 



SYNTAX 

L[<address> f<drive> <record> <record>]l 



COMMENTS 

Set BX:CX to the number of bytes read. The 
file must have been named either when DEBUG was 
started or with the N command. Both the DEBUG 
invocation and the N command format a filename 
properly in the normal format of a file control 
block at CS:5C. 

If the L command is typed without any 
parameters, DEBUG loads the file into memory 
beginning at address CStlOO and sets BX:CX to 
the number of bytes loaded. If the L command 
is typed with an address parameter, loading 
begins at the memory <address> specified. If L 
is typed with all parameters, absolute disk 
sectors are loaded, not a file. The <record>s 
are taken from the <drive> specified (the drive 
designation is numeric here — 0=A: , 1=B: , 2=C: , 
etc.); DEBUG begins loading with the first 
<record> specified, and continues until the 
number of sectors specified in the second 
<record> have been loaded. 



EXAMPLE 



Assume that the following commands are typed: 

A > DEBUG 
-NFILE.COM 

Now, to load' FILE.COM, type: 

L 

DEBUG loads the file and then displays the 
DEBUG prompt. Assume that you want to load 
only portions of a file or certain records from 
a disk. To do this, type: 

L04BA:100 2 OF 6D 

DEBUG then loads 109 (6D hex) records beginning 
with logical record number 15 into memory 
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beginning at address 04BA:0100. When the 
records have been loaded, DEBUG simply returns 
the - prompt. 

If the file has a .EXE extension, it is 
relocated to the load address specified in the 
header of the .EXE file: the <address> 
parameter is always ignored for .EXE files. 
The header itself is stripped off the .EXE file 
before it is loaded into memory. Thus the size 
of an .EXE file on disk will differ from its 
size in memory. 

If the file named by the Name command or 
specified when DEBUG is started is a .HEX file, 
then typing the L command with no parameters 
causes DEBUG to load the file beginning at the 
address specified in the .HEX file. If the L 
command includes the option <address>, DEBUG 
adds the <address> specified in the L command 
to the address found in the .HEX file to 
determine the start address for loading the 
file. 
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NAME 

Move 



PURPOSE 

Moves the block of memory specified by <range> 
to the location beginning at the <address> 
specified. 



SYNTAX 



M<range> <address> 



COMMENTS 

Overlapping moves (i.e., moves where part of 
the block overlaps some of the current 
addresses) are always performed without loss of 
data. Addresses that could be overwritten are 
moved first. The sequence for moves from 
higher addresses to lower addresses is to move 
the data beginning at the block's lowest 
address and then to work towards the highest. 
The sequence for moves from lower addresses to 
higher addresses is to move the data beginning 
at the block's highest address and to work 
towards the lowest. 

Note that if the addresses in the block being 
moved will not have new data written to them, 
the data there before the move will remain. 
The M command copies the data from one area 
into another, in the sequence described, and 
writes over the new addresses. This is why the 
sequence of the move is important. 



EXAMPLE 



Assume that you type: 

MCSrlOO 110 CS:500 

DEBUG first moves address CS:110 to address 
CS:510, then CS:10F to CS:50F, and so on until 
CS:100 is moved to CS:500. You should type the 
D command, using the <address> typed for the M 
command, to review the results of the move. 
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NAME 



PURPOSE 



SYNTAX 



Name 



Sets filenames, 



N<f ilename> (<f ilename> . . . ] 



COMMENTS 



The Name command performs two functions. 
First, Name is used to assign a filename for a 
later Load or Write command. Thus, if you 
start DEBUG without naming any file to be 
debugged, then the N<filename> command must be 
typed before a file can be loaded. Second, 
Name is used to assign filename parameters to 
the file being debugged. In this case. Name 
accepts a list of parameters that are used by 
the file being debugged. 



These two functions overlap, 
following set of DEBUG commands: 



Consider the 



-NFILE1.EXE 

-L 

-G 

Because of the effects of the Name command. 
Name will perform the following steps: 

1. (N)ame assigns the filename FILE1.EXE to 
the filename to be used in any later Load 
or Write commands. 

2. (N)ame also assigns the filename FILE1.EXE 
to the first filename parameter used by any 
program that is later debugged. 

3. (L)oad loads FILE1.EXE into memory. 



(G)o causes FILEl.EXE to be executed with 
FILE1.EXE as the single filename parameter 

(that is, FILEl.EXE is executed as if 
FILEl.EXE had been typed at the command 
level) . 
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A more useful chain of commands might look like 
this: 

-NFILE1.EXE 

-L 

-NFILE2.DAT FILE3.DAT 

-G 

Here, Name sets FILE1.EXE as the filename for 
the subsequent Load command. The Load command 
loads FILE1.EXE into memory, and then the Name 
command is used again, this time to specify the 
parameters to be used by FILE1.EXE. Finally, 
when the Go command is executed, FILE1.EXE is 
executed as if FILEl PILE2.DAT FILE3.DAT had 
been typed at the MS-DOS command level. Note 
that if a Write command were executed at this 
point, then FILE1.EXE — the file being 
debugged — would be saved with the name 
FILE2.DAT1 To avoid such undesired results, 
you should always execute a Name command before 
either a Load or a Write. 

There are four regions of memory that can be 
affected by the Name command: 

CS:5C FCB for file 1 

CS:6C FCB for file 2 

CS:80 Count of characters 

CS:81 All characters typed 

A File Control Block (FCB) for the first 
filename parameter given to the Name command is 
set up at CS:5C. If a second filename 
parameter is typed, then an FCB is set up for 
it beginning at CS:6C. The number of 
characters typed in the Name command (exclusive 
of the first character, "N") is given at 
location CS:80. The actual stream of 
characters given by the Name command (again, 
exclusive of the letter "N") begins at CS:81. 
Note that this stream of characters may contain 
switches and delimiters that would be legal in 
any command typed at the MS-DOS command level. 



EXAMPLE 



A typical use of the Name command is: 

DEBUG PR0G.COM 
-NPARAMl PARAM2/C 
-G 
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In this case, the Go command executes the file 
in memory as if the following command line had 
been typed: 

PROG PARAMl PARAM2/C 

Testing and debugging therefore reflect a 
normal runtime environment for PR0G.COM. 
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NAME 

Output 

PURPOSE 

Sends the <byte> specified to the output port 
specified by <value>. 



SYNTAX 

0<value> <byte> 



COMMENTS 

A 16-bit port address is allowed. 



EXAMPLE 

Type: 



02F8 4F 

DEBUG outputs the byte value 4F to output port 
2F8. 
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NAME 

Quit 



PURPOSE 

Terminates the DEBUG utility. 



SYNTAX 

Q 



COMMENTS ' 

The Q command takes n6 parameters and exits 
DEBUG without saving the file currently being 
operated on. You are returned to the MS-DOS 
command level. 



EXAMPLE 

To end the debugging session, type; 

Q< RETURN > 



DEBUG has been terminated, and control returns 
to the MS-DOS command level. 
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NAME 



PURPOSE 



SYNTAX 



Register 



Displays the contents of one or more CPU 
registers. 



Rf<register-naroe>I 



COMMENTS 



If no <register-name> is typed, the R command 
dumps the register save area and displays the 
contents of all registers and flags. 

If a register name is typed, the 16-bit value 
of that register is displayed in hexadecimal, 
and then a colon appears as a prompt. You then 
either type a <value> to change the register, 
or simply press the <RETURN> key if no change 
is wanted. 

The only valid <register-name>s are: 



AX 


BP 


SS 




BX 


SI 


CS 




CX 


DI 


IP 


(IP and PC both refer 


DX 


DS 


PC 


to the Instruction 


SP 


ES 


F 


Pointer. ) 



Any other entry for <register-name> results in 
a BR Error message. 

If F is entered as the <register-name> , DEBUG 
displays each flag with a two-character 
alphabetic code. To alter any flag, type the 
opposite two-letter code. The flags are either 
set or cleared. 
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The flags are listed below with their codes for 
SET and CLEAR: 



FLAG NAME 


SET 


CLEAR 


Overflow 


OV 


NV 


Direction 


DN Decrement 


UP Increment 


Interrupt 


EI Enabled 


DI Disabled 


Sign 


NG Negative 


PL Plus 


Zero 


ZR 


NZ 


Auxiliary 
Carry 


AC 


NA 


Parity 


PE Even 


PC Odd 


Carry 


CY 


NC 



Whenever you type the command RF, the flags are 
displayed in the order shown above in a row at 
the beginning of a line. At the end of the 
list of flags, DEBUG displays a hyphen (-) . 
You may enter new flag values as alphabetic 
pairs. The new flag values can be entered in 
any order. You do not have to leave spaces 
between the flag entries. To exit the R 
command, press the <RETURN> key. Flags for 
which new values were not entered remain 
unchanged. 

If more than one value is entered for a flag, 
DEBUG returns a DF Error message. If you enter 
a flag code other than those shown above, DEBUG 
returns a BF Error message. In both cases, the 
flags up to the error in the list are changed; 
flags at and after the error are not. 

At startup, the segment registers are set to 
the bottom of free memory, the Instruction 
Pointer is set to OlOOH, all flags are cleared, 
and the remaining registers are set to zero. 
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EXAMPLE 

Type: 



DEBUG displays all registers, flags, and the 
decoded instruction for the current location. 
If the location is CSillA, then the display 
will look similar to this: 

AX=OEOO BX«OOFF CX=0007 DX»01PF SP=039D BP=0000 
SI=005C DI=0000 DS=04BA ES=04BA SS=04BA CS<=04BA 
IP=011A NV UP DI NG NZ AC PE NC 
04BA:011A CD21 INT 21 



If you type: 

RF 
DEBUG will display the flags: 

NV UP DI NG NZ AC PE NC - _ 

Nowr type any valid flag designation, in any 
order, with or without spaces. 

For example: 

NV UP DI NG NZ AC PE NC - PLEICY<RETURN> 

DEBUG responds only with the DEBUG prompt. To 
see the changes, type either the R or RF 
command : 

RF 

NV UP EI PL NZ AC PE CY - _ 

Press <RETURN> to leave the flags this way, or 
to specify different flag values. 
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NAME 

Search 

PURPOSE 

Searches the <range> specified for the <list> 
of bytes specified. 



SYNTAX 



S<range> <list> 



COMMENTS 

The <list> may contain one or more bytes, each 
separated by a space or comma. If the <list> 
contains more than one byte, only the first 
address of the byte string is returned. If the 
<list> contains only one byte, all addresses of 
the byte in hhe <ranqe> are displayed. 



EXAMPLE 



If you type: 

SCSilOO 110 41 

DEBUG will display a response similar to this: 

04BA:0104 
04BA:010D 
-type: 



DEBUG (T)race Page 2-30 

NAME 

Trace 



PURPOSE 

Executes one instruction and displays the 
contents of all registers and flags, and the 
decoded instruction. 



SYNTAX 



T{=<address>] [ <value>] 



COMMENTS 

If the optional =<address> is typed, tracing 
occurs at the =<addres8> specified. The 
optional <value> causes DEBUG to execute and 
trace the number of steps specified by <value> . 

The T command uses the hardware trace mode of 
the 8086 or 8088 microprocessor. Consequently, 
you may also trace instructions stored in ROM 
(Read Only Memory) . 



EXAMPLE 



Type: 



DEBUG returns a display of the registers, 
flags, and decoded instruction for that one 
instruction. Assume that the current position 
is 04BA:011A; DEBUG might return the display: 

AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP«0000 
SI=005C DI=0000 DS=04BA ES«=04BA SS=04BA CS=04BA 
IP=011A NV UP DI NG NZ AC PE NC 
04BA:011A CD21 INT 21 

If you type 

T=011A 10 
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DEBUG executes sixteen (10 hex) instructions 
beginning at OllA in the current segment, and 
then displays all registers and flags for each 
instruction as it is executed. The display 
scrolls away until the last instruction is 
executed. Then the display stops, and you can 
see the register and flag values for the last 
few instructions performed. Remember that 
<CONTROL-S> suspends the display at any point, 
so that you can study the registers and flags 
for any instruction. 
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Unassemble 



Disassembles bytes and displays the source 
statements that correspond to them, with 
addresses and byte values. 



U [<range>] 



COMMENTS 



The display of disassembled code looks like a 
listing for an assembled file. If you type the 
U command without parameters, 20 hexadecimal 
bytes are disassembled at the first address 
after that displayed by the previous Unassemble 
command. If you type the U command with the 
<range> parameter, then DEBUG disassembles all 
bytes in the range. If the <range> is given as 
an <address> only, then 20H bytes are 
disassembled instead of BOH. 



EXAMPLE 



Type: 



U04BA:100 LlO 



DEBUG disasse 


mbles 16 


bytes beginning 


address 04BA:0100: 






04BA:0100 


206472 


AND 


{SI+72] ,AH 


04BA:0103 


69 


DB 


69 


04BA:0104 


7665 


JBE 


016B 


04BA:0106 


207370 


AND 


[BP+DI+70] ,DH 


04BA:0109 


65 


DB 


65 


04BA:010A 


63 


DB 


63 


04BA:010B 


69 


DB 


69 


04BA:010C 


66 


DB 


66 


04BA:010D 


69 


DB 


69 


04BA:010E 


63 


DB 


63 


04BA:010F 


61 


DB 


61 


If you type 








U04ba:0100 0108 







at 
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The display will show; 



04BA:0100 
04BA:0103 
04BA:0104 
04BA:0106 



206472 
69 

7665 
207370 



AND - (SI+721 ,AH 

DB 69 

JBE 016B 

AND (BP+DI+70) ,DH 



If the bytes in some addresses are altered, the 
disassembler alters the instruction statements. 
The U command can be typed for the changed 
locations, the new instructions viewed, and the 
disassembled code used to edit the source file. 
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NAME 

Write 

PURPOSE 

Writes the file being debugged to a disk file. 

SYNTAX 

W[<address>( <drive> <record> <record>]] 

COMMENTS 

If you type W with no parameters, BX:CX must 
already be set to the number of bytes to be 
written; the file is written beginning from 
CStlOO. If the W command is typed with 3ust an 
address, then the file is written beginning at 
that address. If a G or T command has been 
used, BX:CX must be reset before using the 
Write command without parameters. Note that if 
a file is loaded and modified, the name, 
length, and starting address are all set 
correctly to save the modified file (as long as 
the length has not changed) . 

The file must have been named either with the 
DEBUG invocation command or with the N command 
(refer to the Name command earlier in this 
manual) . Both the DEBUG invocation and the N 
command format a filename properly in the 
normal format of a file control block at CS:5C. 

If the W command is typed with parameters, the 
write begins from the memory address specified; 
the file is written to the <drive> specified 
(the drive designation is numeric here — 0=A: , 
1»B:, 2=C: , etc.); DEBUG writes the file 
beginning at the logical record number 
specified by the first <record>; DEBUG 
continues to write the file until the number of 
sectors specified in the. second <record> have 
been written. 

WARNING 

Writing to absolute sectors is 
EXTREMELY dangerous because the process 
bypasses the file handler. 
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EXAMPLE 



Type! 



W 



DEBUG will write the file to disk and then 
display the DEBUG prompt. Two examples are 
shown below. 



WCStlOO 1 37 2B 



DEBUG writes out the contents of memory, 
beginning with the address CS:100 to the disk 
in drive B:. The data written out starts in 
disk logical record number 37H and consists of 
2BH records. When the write is complete, DEBUG 
displays the prompt; 

WCSilOO 1 37 2B 
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2.3 ERROR MESSAGES 

During the DEBUG session, you may receive any of the 

following error messages. Each error terminates the DEBUG 

command under which it occurred, but does not terminate 
DEBUG itself. 



ERROR CODE DEFINITION 

BF Bad flag 

You attempted to alter a flag, but the 

characters typed were not one of the 

acceptable pairs of flag values. See the 

Register command for the list of 
acceptable flag entries. 

BP Too many breakpoints 

You specified more than ten breakpoints as 
parameters to the G command. Retype the 
Go command with ten or fewer breakpoints. 

BR Bad register 

You typed the R command with an invalid 
register name. See the Register command 
for the list of valid register names. 

DP Double flag 

You typed two values for one flag. You 
may specify a flag value only once per RF 
command . 
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